Report

Note

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

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

Reports are scoped to the app that created them. When an app creates a report, other apps can't view, modify, or delete that report. Also, apps can't access reports that were created from the Shopify admin.

Setting reports publishing permissions

To give reports publishing permissions to your app, 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. When you create a report, the API will return custom_app_reports.

id
"id": 517154478

The unique numeric identifier for the report.

name
"name": "My App Report"

The name of the report. Maximum length: 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 (ISO 8601) when the report was last modified.

Endpoints

GET /admin/reports.json
Retrieves a list of reports created by your app
ids

A comma-separated list of report IDs.

limit

The amount of results to return.

(default: 50, maximum: 250)
page

The page of results 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.

Retrieve a list of 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": "2018-07-05T12:41:00-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"
    }
  ]
}

Retrieve a 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"
    }
  ]
}

Retrieve a 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": "2018-07-05T12:41:00-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"
    }
  ]
}

Retrieve a list of 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"
    }
  ]
}

Retrieve a 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": "2018-07-05T12:41:00-04:00",
      "category": "custom_app_reports"
    }
  ]
}
GET /admin/reports/517154478.json
Retrieves a single report created by your app
fields

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

Retrieve a single report

GET /admin/reports/#{report_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"
  }
}

Retrieve a single report, showing only particular fields

GET /admin/reports/#{report_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
Creates a new report
name

The name of the report. Maximum length: 255 characters.

shopify_ql

The ShopifyQL the report will query.

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": "2018-07-05T13:12:58-04:00",
    "category": "custom_app_reports"
  }
}
PUT /admin/reports/517154478.json
Updates a report

Update an existing report

PUT /admin/reports/#{report_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": "2018-07-05T13:12:59-04:00",
    "category": "custom_app_reports"
  }
}
DELETE /admin/reports/517154478.json
Deletes a report

Delete an existing report

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

Sign up for a Partner account to get started.

Sign up