Report

Shopify Advanced and Shopify Plus

The Reports Publishing API and the Reports resource are available to Shopify Advanced and Shopify Plus merchants only.

You can use the Reports Publishing API to publish reports to the Reports page in the Shopify admin. For example, a shirt fulfillment app could publish a report that shows the sales of shirts by the marketing campaign. The reports are based on queries written in ShopifyQL.

The Reports Publishing API and the Reports resource are available to Shopify Advanced and Shopify Plus merchants only.

Setting reports publishing permissions

Add the write_reports permission to your OAuth requested scopes.

What you can do with Report

The Shopify API lets you do the following with the Report resource. More detailed versions of these general actions may be available:

Report properties

category
"category": "custom_app_reports"

The category for the report. The value returned by the API is "custom_app_reports".

id
"id": 517154478

A unique numeric identifier for the report.

name
"name": "My App Report"

The name of the report. Limit of 255 characters.

shopify_ql
"shopify_ql": "SHOW sales BY country FROM order SINCE -1m UNTIL today ORDER BY sales"

The ShopifyQL query that generates the report. See Shopify Query Language.

updated_at
"updated_at": "2008-02-01T19:00:00-05:00"

The date and time when the report was last modified. The API returns this value in ISO 8601 format.

Endpoints

GET /admin/reports.json
Retrieve a list of reports
ids

A comma-separated list of report IDs

limit

Amount of results

(default: 50) (maximum: 250)
page

Page to show

(default: 1)
since_id

Restrict results to after the specified ID

updated_at_min

Show reports last updated after date (format: 2014-04-25T16:15:47-04:00)

updated_at_max

Show reports last updated before date (format: 2014-04-25T16:15:47-04:00)

fields

A comma-separated list of fields to include in the response

List all reports

GET /admin/reports.json
View Response
HTTP/1.1 200 OK
{
  "reports": [
    {
      "id": 752357116,
      "name": "Custom App Report 2",
      "shopify_ql": "SHOW total_sales BY country FROM orders ORDER BY total_sales",
      "updated_at": "2017-07-05T14:25:46-04:00",
      "category": "custom_app_reports"
    },
    {
      "id": 517154478,
      "name": "Wholesale Sales Report",
      "shopify_ql": "SHOW sales BY country FROM order WHERE channel.api_client_id = 123 SINCE -1m UNTIL today",
      "updated_at": "2017-04-10T16:33:22-04:00",
      "category": "custom_app_reports"
    }
  ]
}

List reports last updated after 2005-07-31 15:57:11 in the EDT timezone

GET /admin/reports.json?updated_at_min=2005-07-31 15:57:11 EDT -04:00
View Response
HTTP/1.1 200 OK
{
  "reports": [
    {
      "id": 752357116,
      "name": "Custom App Report 2",
      "shopify_ql": "SHOW total_sales BY country FROM orders ORDER BY total_sales",
      "updated_at": "2017-07-05T14:25:46-04:00",
      "category": "custom_app_reports"
    },
    {
      "id": 517154478,
      "name": "Wholesale Sales Report",
      "shopify_ql": "SHOW sales BY country FROM order WHERE channel.api_client_id = 123 SINCE -1m UNTIL today",
      "updated_at": "2017-04-10T16:33:22-04:00",
      "category": "custom_app_reports"
    }
  ]
}

List all reports, showing only some attributes

GET /admin/reports.json?fields=id,shopify_ql
View Response
HTTP/1.1 200 OK
{
  "reports": [
    {
      "id": 752357116,
      "shopify_ql": "SHOW total_sales BY country FROM orders ORDER BY total_sales"
    },
    {
      "id": 517154478,
      "shopify_ql": "SHOW sales BY country FROM order WHERE channel.api_client_id = 123 SINCE -1m UNTIL today"
    }
  ]
}

List of specific reports

GET /admin/reports.json?ids=517154478
View Response
HTTP/1.1 200 OK
{
  "reports": [
    {
      "id": 517154478,
      "name": "Wholesale Sales Report",
      "shopify_ql": "SHOW sales BY country FROM order WHERE channel.api_client_id = 123 SINCE -1m UNTIL today",
      "updated_at": "2017-04-10T16:33:22-04:00",
      "category": "custom_app_reports"
    }
  ]
}

List all reports after the specified ID

GET /admin/reports.json?since_id=123
View Response
HTTP/1.1 200 OK
{
  "reports": [
    {
      "id": 517154478,
      "name": "Wholesale Sales Report",
      "shopify_ql": "SHOW sales BY country FROM order WHERE channel.api_client_id = 123 SINCE -1m UNTIL today",
      "updated_at": "2017-04-10T16:33:22-04:00",
      "category": "custom_app_reports"
    },
    {
      "id": 752357116,
      "name": "Custom App Report 2",
      "shopify_ql": "SHOW total_sales BY country FROM orders ORDER BY total_sales",
      "updated_at": "2017-07-05T14:25:46-04:00",
      "category": "custom_app_reports"
    }
  ]
}
GET /admin/reports/517154478.json
Retrieve a single report
fields

A comma-separated list of fields to include in the response

Get a representation of a single report

GET /admin/reports/#{id}.json
View Response
HTTP/1.1 200 OK
{
  "report": {
    "id": 517154478,
    "name": "Wholesale Sales Report",
    "shopify_ql": "SHOW sales BY country FROM order WHERE channel.api_client_id = 123 SINCE -1m UNTIL today",
    "updated_at": "2017-04-10T16:33:22-04:00",
    "category": "custom_app_reports"
  }
}

Get only particular fields

GET /admin/reports/#{id}.json?fields=id,shopify_ql
View Response
HTTP/1.1 200 OK
{
  "report": {
    "id": 517154478,
    "shopify_ql": "SHOW sales BY country FROM order WHERE channel.api_client_id = 123 SINCE -1m UNTIL today"
  }
}
POST /admin/reports.json
Create a new report for a merchant’s shop
name

The name of the report. Limit of 255 characters

shopify_ql

The ShopifyQL the report will query

category

The category for the report. The value returned by the API is "custom_app_reports"

Create a new report

POST /admin/reports.json
{
  "report": {
    "name": "A new app report",
    "shopify_ql": "SHOW total_sales BY country FROM order SINCE -1m UNTIL today ORDER BY total_sales"
  }
}
View Response
HTTP/1.1 201 Created
{
  "report": {
    "id": 1016888664,
    "name": "A new app report",
    "shopify_ql": "SHOW total_sales BY country FROM order SINCE -1m UNTIL today ORDER BY total_sales",
    "updated_at": "2017-07-05T14:25:59-04:00",
    "category": "custom_app_reports"
  }
}
PUT /admin/reports/517154478.json
Modify a report previously created by your app

Update an existing report

PUT /admin/reports/#{id}.json
{
  "report": {
    "id": 517154478,
    "name": "Changed Report Name",
    "shopify_ql": "SHOW total_sales BY country FROM order SINCE -12m UNTIL today ORDER BY total_sales"
  }
}
View Response
HTTP/1.1 200 OK
{
  "report": {
    "id": 517154478,
    "name": "Changed Report Name",
    "shopify_ql": "SHOW total_sales BY country FROM order SINCE -12m UNTIL today ORDER BY total_sales",
    "updated_at": "2017-07-05T14:25:58-04:00",
    "category": "custom_app_reports"
  }
}
DELETE /admin/reports/517154478.json
Delete a report previously created by your app

Delete an existing report

DELETE /admin/reports/#{id}.json
View Response
HTTP/1.1 200 OK
{}