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	`plain "category": "custom_app_reports"` The category for the report. When you create a report, the API will return `custom_app_reports`.
id	`plain "id": 517154478` The unique numeric identifier for the report.
name	`plain "name": "My App Report"` The name of the report. Maximum length: 255 characters.
shopify_ql	`plain "shopify_ql": "SHOW total_sales BY order_id FROM sales SINCE -1m UNTIL today ORDER BY total_sales"` The ShopifyQL query that generates the report. See Shopify Query Language.
updated_at	`plain "updated_at": "2008-02-01T19:00:00-05:00"` The date and time (ISO 8601) when the report was last modified.

Endpoints

GET/admin/api/2021-01/reports.json Retrieves a list of reports. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the <font style="background-color:#F4F6F8;">page</font> parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.

ids	A comma-separated list of report IDs.
limit	The amount of results to return. (default: `50` , maximum: `250` )
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/api/2021-01/reports.json

View Response

Retrieve a list of specific reports

GET /admin/api/2021-01/reports.json?ids=517154478

View Response

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

GET /admin/api/2021-01/reports.json?updated_at_min=2005-07-31 15:57:11 EDT -04:00

View Response

Retrieve a list of all reports, showing only some attributes

GET /admin/api/2021-01/reports.json?fields=id,shopify_ql

View Response

Retrieve a list all reports after the specified ID

GET /admin/api/2021-01/reports.json?since_id=123

View Response

GET/admin/api/2021-01/reports/{report_id}.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/api/2021-01/reports/517154478.json

View Response

Retrieve a single report, showing only particular fields

GET /admin/api/2021-01/reports/517154478.json?fields=id,shopify_ql

View Response

POST/admin/api/2021-01/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/api/2021-01/reports.json

{

“report”: {

"name": "A new app report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales SINCE -1m UNTIL today ORDER BY total_sales"

}

View Response

PUT/admin/api/2021-01/reports/{report_id}.json Updates a report

Update an existing report

PUT /admin/api/2021-01/reports/517154478.json

{

“report”: {

"id": 517154478,
"name": "Changed Report Name",
"shopify_ql": "SHOW total_sales BY order_id FROM sales SINCE -12m UNTIL today ORDER BY total_sales"

}

View Response

DELETE/admin/api/2021-01/reports/{report_id}.json Deletes a report

Delete an existing report

DELETE /admin/api/2021-01/reports/517154478.json

View Response