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:
- GET /admin/api/2019-10/reports.json Retrieves a list of reports
- GET /admin/api/2019-10/reports/{report_id}.json Retrieves a single report
- POST /admin/api/2019-10/reports.json Creates a new report
- PUT /admin/api/2019-10/reports/{report_id}.json Updates a report
- DELETE /admin/api/2019-10/reports/{report_id}.json Deletes a report
Report properties
category |
The category for the report. When you create a report, the API will return |
id |
The unique numeric identifier for the report. |
name |
The name of the report. Maximum length: 255 characters. |
shopify_ql |
The ShopifyQL query that generates the report. See Shopify Query Language. |
updated_at |
The date and time (ISO 8601) when the report was last modified. |
Endpoints
page
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/2019-10/reports.json
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 752357116,
"name": "Custom App Report 2",
"shopify_ql": "SHOW total_sales BY order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
},
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2019-10/reports.json?ids=517154478
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2019-10/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 order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
},
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2019-10/reports.json?fields=id,shopify_ql
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 752357116,
"shopify_ql": "SHOW total_sales BY order_id FROM sales ORDER BY total_sales"
},
{
"id": 517154478,
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE api_client_id == 123 SINCE -1m UNTIL today"
}
]
}
Retrieve a list all reports after the specified ID
GET /admin/api/2019-10/reports.json?since_id=123
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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 order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
}
]
}
fields
|
A comma-separated list of fields to include in the response. |
Retrieve a single report
GET /admin/api/2019-10/reports/517154478.json
View Response
HTTP/1.1 200 OK
{
"report": {
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2019-10/reports/517154478.json?fields=id,shopify_ql
View Response
HTTP/1.1 200 OK
{
"report": {
"id": 517154478,
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE api_client_id == 123 SINCE -1m UNTIL today"
}
}
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/2019-10/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
HTTP/1.1 201 Created
{
"report": {
"id": 1016888664,
"name": "A new app report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales SINCE -1m UNTIL today ORDER BY total_sales",
"updated_at": "2021-02-05T21:00:16-05:00",
"category": "custom_app_reports"
}
}
Update an existing report
PUT /admin/api/2019-10/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
HTTP/1.1 200 OK
{
"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",
"updated_at": "2021-02-05T21:00:18-05:00",
"category": "custom_app_reports"
}
}
Delete an existing report
DELETE /admin/api/2019-10/reports/517154478.json
View Response
HTTP/1.1 200 OK
{
}
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:
- GET /admin/api/2020-01/reports.json Retrieves a list of reports
- GET /admin/api/2020-01/reports/{report_id}.json Retrieves a single report
- POST /admin/api/2020-01/reports.json Creates a new report
- PUT /admin/api/2020-01/reports/{report_id}.json Updates a report
- DELETE /admin/api/2020-01/reports/{report_id}.json Deletes a report
Report properties
category |
The category for the report. When you create a report, the API will return |
id |
The unique numeric identifier for the report. |
name |
The name of the report. Maximum length: 255 characters. |
shopify_ql |
The ShopifyQL query that generates the report. See Shopify Query Language. |
updated_at |
The date and time (ISO 8601) when the report was last modified. |
Endpoints
page
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/2020-01/reports.json
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 752357116,
"name": "Custom App Report 2",
"shopify_ql": "SHOW total_sales BY order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
},
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2020-01/reports.json?ids=517154478
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2020-01/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 order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
},
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2020-01/reports.json?fields=id,shopify_ql
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 752357116,
"shopify_ql": "SHOW total_sales BY order_id FROM sales ORDER BY total_sales"
},
{
"id": 517154478,
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE api_client_id == 123 SINCE -1m UNTIL today"
}
]
}
Retrieve a list all reports after the specified ID
GET /admin/api/2020-01/reports.json?since_id=123
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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 order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
}
]
}
fields
|
A comma-separated list of fields to include in the response. |
Retrieve a single report
GET /admin/api/2020-01/reports/517154478.json
View Response
HTTP/1.1 200 OK
{
"report": {
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2020-01/reports/517154478.json?fields=id,shopify_ql
View Response
HTTP/1.1 200 OK
{
"report": {
"id": 517154478,
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE api_client_id == 123 SINCE -1m UNTIL today"
}
}
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/2020-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
HTTP/1.1 201 Created
{
"report": {
"id": 1016888664,
"name": "A new app report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales SINCE -1m UNTIL today ORDER BY total_sales",
"updated_at": "2021-02-05T21:00:16-05:00",
"category": "custom_app_reports"
}
}
Update an existing report
PUT /admin/api/2020-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
HTTP/1.1 200 OK
{
"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",
"updated_at": "2021-02-05T21:00:18-05:00",
"category": "custom_app_reports"
}
}
Delete an existing report
DELETE /admin/api/2020-01/reports/517154478.json
View Response
HTTP/1.1 200 OK
{
}
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:
- GET /admin/api/2020-04/reports.json Retrieves a list of reports
- GET /admin/api/2020-04/reports/{report_id}.json Retrieves a single report
- POST /admin/api/2020-04/reports.json Creates a new report
- PUT /admin/api/2020-04/reports/{report_id}.json Updates a report
- DELETE /admin/api/2020-04/reports/{report_id}.json Deletes a report
Report properties
category |
The category for the report. When you create a report, the API will return |
id |
The unique numeric identifier for the report. |
name |
The name of the report. Maximum length: 255 characters. |
shopify_ql |
The ShopifyQL query that generates the report. See Shopify Query Language. |
updated_at |
The date and time (ISO 8601) when the report was last modified. |
Endpoints
page
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/2020-04/reports.json
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 752357116,
"name": "Custom App Report 2",
"shopify_ql": "SHOW total_sales BY order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
},
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2020-04/reports.json?ids=517154478
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2020-04/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 order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
},
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2020-04/reports.json?fields=id,shopify_ql
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 752357116,
"shopify_ql": "SHOW total_sales BY order_id FROM sales ORDER BY total_sales"
},
{
"id": 517154478,
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE api_client_id == 123 SINCE -1m UNTIL today"
}
]
}
Retrieve a list all reports after the specified ID
GET /admin/api/2020-04/reports.json?since_id=123
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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 order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
}
]
}
fields
|
A comma-separated list of fields to include in the response. |
Retrieve a single report
GET /admin/api/2020-04/reports/517154478.json
View Response
HTTP/1.1 200 OK
{
"report": {
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2020-04/reports/517154478.json?fields=id,shopify_ql
View Response
HTTP/1.1 200 OK
{
"report": {
"id": 517154478,
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE api_client_id == 123 SINCE -1m UNTIL today"
}
}
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/2020-04/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
HTTP/1.1 201 Created
{
"report": {
"id": 1016888664,
"name": "A new app report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales SINCE -1m UNTIL today ORDER BY total_sales",
"updated_at": "2021-02-05T21:00:16-05:00",
"category": "custom_app_reports"
}
}
Update an existing report
PUT /admin/api/2020-04/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
HTTP/1.1 200 OK
{
"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",
"updated_at": "2021-02-05T21:00:18-05:00",
"category": "custom_app_reports"
}
}
Delete an existing report
DELETE /admin/api/2020-04/reports/517154478.json
View Response
HTTP/1.1 200 OK
{
}
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:
- GET /admin/api/2020-07/reports.json Retrieves a list of reports
- GET /admin/api/2020-07/reports/{report_id}.json Retrieves a single report
- POST /admin/api/2020-07/reports.json Creates a new report
- PUT /admin/api/2020-07/reports/{report_id}.json Updates a report
- DELETE /admin/api/2020-07/reports/{report_id}.json Deletes a report
Report properties
category |
The category for the report. When you create a report, the API will return |
id |
The unique numeric identifier for the report. |
name |
The name of the report. Maximum length: 255 characters. |
shopify_ql |
The ShopifyQL query that generates the report. See Shopify Query Language. |
updated_at |
The date and time (ISO 8601) when the report was last modified. |
Endpoints
page
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/2020-07/reports.json
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 752357116,
"name": "Custom App Report 2",
"shopify_ql": "SHOW total_sales BY order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
},
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2020-07/reports.json?ids=517154478
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2020-07/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 order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
},
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2020-07/reports.json?fields=id,shopify_ql
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 752357116,
"shopify_ql": "SHOW total_sales BY order_id FROM sales ORDER BY total_sales"
},
{
"id": 517154478,
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE api_client_id == 123 SINCE -1m UNTIL today"
}
]
}
Retrieve a list all reports after the specified ID
GET /admin/api/2020-07/reports.json?since_id=123
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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 order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
}
]
}
fields
|
A comma-separated list of fields to include in the response. |
Retrieve a single report
GET /admin/api/2020-07/reports/517154478.json
View Response
HTTP/1.1 200 OK
{
"report": {
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2020-07/reports/517154478.json?fields=id,shopify_ql
View Response
HTTP/1.1 200 OK
{
"report": {
"id": 517154478,
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE api_client_id == 123 SINCE -1m UNTIL today"
}
}
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/2020-07/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
HTTP/1.1 201 Created
{
"report": {
"id": 1016888664,
"name": "A new app report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales SINCE -1m UNTIL today ORDER BY total_sales",
"updated_at": "2021-02-05T21:00:16-05:00",
"category": "custom_app_reports"
}
}
Update an existing report
PUT /admin/api/2020-07/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
HTTP/1.1 200 OK
{
"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",
"updated_at": "2021-02-05T21:00:18-05:00",
"category": "custom_app_reports"
}
}
Delete an existing report
DELETE /admin/api/2020-07/reports/517154478.json
View Response
HTTP/1.1 200 OK
{
}
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:
- GET /admin/api/2020-10/reports.json Retrieves a list of reports
- GET /admin/api/2020-10/reports/{report_id}.json Retrieves a single report
- POST /admin/api/2020-10/reports.json Creates a new report
- PUT /admin/api/2020-10/reports/{report_id}.json Updates a report
- DELETE /admin/api/2020-10/reports/{report_id}.json Deletes a report
Report properties
category |
The category for the report. When you create a report, the API will return |
id |
The unique numeric identifier for the report. |
name |
The name of the report. Maximum length: 255 characters. |
shopify_ql |
The ShopifyQL query that generates the report. See Shopify Query Language. |
updated_at |
The date and time (ISO 8601) when the report was last modified. |
Endpoints
page
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/2020-10/reports.json
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 752357116,
"name": "Custom App Report 2",
"shopify_ql": "SHOW total_sales BY order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
},
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2020-10/reports.json?ids=517154478
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2020-10/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 order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
},
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2020-10/reports.json?fields=id,shopify_ql
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 752357116,
"shopify_ql": "SHOW total_sales BY order_id FROM sales ORDER BY total_sales"
},
{
"id": 517154478,
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE api_client_id == 123 SINCE -1m UNTIL today"
}
]
}
Retrieve a list all reports after the specified ID
GET /admin/api/2020-10/reports.json?since_id=123
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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 order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
}
]
}
fields
|
A comma-separated list of fields to include in the response. |
Retrieve a single report
GET /admin/api/2020-10/reports/517154478.json
View Response
HTTP/1.1 200 OK
{
"report": {
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2020-10/reports/517154478.json?fields=id,shopify_ql
View Response
HTTP/1.1 200 OK
{
"report": {
"id": 517154478,
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE api_client_id == 123 SINCE -1m UNTIL today"
}
}
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/2020-10/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
HTTP/1.1 201 Created
{
"report": {
"id": 1016888664,
"name": "A new app report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales SINCE -1m UNTIL today ORDER BY total_sales",
"updated_at": "2021-02-05T21:00:16-05:00",
"category": "custom_app_reports"
}
}
Update an existing report
PUT /admin/api/2020-10/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
HTTP/1.1 200 OK
{
"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",
"updated_at": "2021-02-05T21:00:18-05:00",
"category": "custom_app_reports"
}
}
Delete an existing report
DELETE /admin/api/2020-10/reports/517154478.json
View Response
HTTP/1.1 200 OK
{
}
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:
- GET /admin/api/2021-01/reports.json Retrieves a list of reports
- GET /admin/api/2021-01/reports/{report_id}.json Retrieves a single report
- POST /admin/api/2021-01/reports.json Creates a new report
- PUT /admin/api/2021-01/reports/{report_id}.json Updates a report
- DELETE /admin/api/2021-01/reports/{report_id}.json Deletes a report
Report properties
category |
The category for the report. When you create a report, the API will return |
id |
The unique numeric identifier for the report. |
name |
The name of the report. Maximum length: 255 characters. |
shopify_ql |
The ShopifyQL query that generates the report. See Shopify Query Language. |
updated_at |
The date and time (ISO 8601) when the report was last modified. |
Endpoints
page
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
HTTP/1.1 200 OK
{
"reports": [
{
"id": 752357116,
"name": "Custom App Report 2",
"shopify_ql": "SHOW total_sales BY order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
},
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2021-01/reports.json?ids=517154478
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2021-01/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 order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
},
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2021-01/reports.json?fields=id,shopify_ql
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 752357116,
"shopify_ql": "SHOW total_sales BY order_id FROM sales ORDER BY total_sales"
},
{
"id": 517154478,
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE api_client_id == 123 SINCE -1m UNTIL today"
}
]
}
Retrieve a list all reports after the specified ID
GET /admin/api/2021-01/reports.json?since_id=123
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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 order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
}
]
}
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
HTTP/1.1 200 OK
{
"report": {
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2021-01/reports/517154478.json?fields=id,shopify_ql
View Response
HTTP/1.1 200 OK
{
"report": {
"id": 517154478,
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE api_client_id == 123 SINCE -1m UNTIL today"
}
}
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
HTTP/1.1 201 Created
{
"report": {
"id": 1016888664,
"name": "A new app report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales SINCE -1m UNTIL today ORDER BY total_sales",
"updated_at": "2021-02-05T21:00:16-05:00",
"category": "custom_app_reports"
}
}
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
HTTP/1.1 200 OK
{
"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",
"updated_at": "2021-02-05T21:00:18-05:00",
"category": "custom_app_reports"
}
}
Delete an existing report
DELETE /admin/api/2021-01/reports/517154478.json
View Response
HTTP/1.1 200 OK
{
}
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:
- GET /admin/api/2021-04/reports.json Retrieves a list of reports
- GET /admin/api/2021-04/reports/{report_id}.json Retrieves a single report
- POST /admin/api/2021-04/reports.json Creates a new report
- PUT /admin/api/2021-04/reports/{report_id}.json Updates a report
- DELETE /admin/api/2021-04/reports/{report_id}.json Deletes a report
Report properties
category |
The category for the report. When you create a report, the API will return |
id |
The unique numeric identifier for the report. |
name |
The name of the report. Maximum length: 255 characters. |
shopify_ql |
The ShopifyQL query that generates the report. See Shopify Query Language. |
updated_at |
The date and time (ISO 8601) when the report was last modified. |
Endpoints
page
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-04/reports.json
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 752357116,
"name": "Custom App Report 2",
"shopify_ql": "SHOW total_sales BY order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
},
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2021-04/reports.json?ids=517154478
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2021-04/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 order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
},
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2021-04/reports.json?fields=id,shopify_ql
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 752357116,
"shopify_ql": "SHOW total_sales BY order_id FROM sales ORDER BY total_sales"
},
{
"id": 517154478,
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE api_client_id == 123 SINCE -1m UNTIL today"
}
]
}
Retrieve a list all reports after the specified ID
GET /admin/api/2021-04/reports.json?since_id=123
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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 order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
}
]
}
fields
|
A comma-separated list of fields to include in the response. |
Retrieve a single report
GET /admin/api/2021-04/reports/517154478.json
View Response
HTTP/1.1 200 OK
{
"report": {
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/2021-04/reports/517154478.json?fields=id,shopify_ql
View Response
HTTP/1.1 200 OK
{
"report": {
"id": 517154478,
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE api_client_id == 123 SINCE -1m UNTIL today"
}
}
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-04/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
HTTP/1.1 201 Created
{
"report": {
"id": 1016888664,
"name": "A new app report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales SINCE -1m UNTIL today ORDER BY total_sales",
"updated_at": "2021-02-05T21:00:16-05:00",
"category": "custom_app_reports"
}
}
Update an existing report
PUT /admin/api/2021-04/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
HTTP/1.1 200 OK
{
"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",
"updated_at": "2021-02-05T21:00:18-05:00",
"category": "custom_app_reports"
}
}
Delete an existing report
DELETE /admin/api/2021-04/reports/517154478.json
View Response
HTTP/1.1 200 OK
{
}
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:
- GET /admin/api/unstable/reports.json Retrieves a list of reports
- GET /admin/api/unstable/reports/{report_id}.json Retrieves a single report
- POST /admin/api/unstable/reports.json Creates a new report
- PUT /admin/api/unstable/reports/{report_id}.json Updates a report
- DELETE /admin/api/unstable/reports/{report_id}.json Deletes a report
Report properties
category |
The category for the report. When you create a report, the API will return |
id |
The unique numeric identifier for the report. |
name |
The name of the report. Maximum length: 255 characters. |
shopify_ql |
The ShopifyQL query that generates the report. See Shopify Query Language. |
updated_at |
The date and time (ISO 8601) when the report was last modified. |
Endpoints
page
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/unstable/reports.json
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 752357116,
"name": "Custom App Report 2",
"shopify_ql": "SHOW total_sales BY order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
},
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/unstable/reports.json?ids=517154478
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/unstable/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 order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
},
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/unstable/reports.json?fields=id,shopify_ql
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 752357116,
"shopify_ql": "SHOW total_sales BY order_id FROM sales ORDER BY total_sales"
},
{
"id": 517154478,
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE api_client_id == 123 SINCE -1m UNTIL today"
}
]
}
Retrieve a list all reports after the specified ID
GET /admin/api/unstable/reports.json?since_id=123
View Response
HTTP/1.1 200 OK
{
"reports": [
{
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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 order_id FROM sales ORDER BY total_sales",
"updated_at": "2021-02-05T20:59:20-05:00",
"category": "custom_app_reports"
}
]
}
fields
|
A comma-separated list of fields to include in the response. |
Retrieve a single report
GET /admin/api/unstable/reports/517154478.json
View Response
HTTP/1.1 200 OK
{
"report": {
"id": 517154478,
"name": "Wholesale Sales Report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE 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/api/unstable/reports/517154478.json?fields=id,shopify_ql
View Response
HTTP/1.1 200 OK
{
"report": {
"id": 517154478,
"shopify_ql": "SHOW total_sales BY order_id FROM sales WHERE api_client_id == 123 SINCE -1m UNTIL today"
}
}
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/unstable/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
HTTP/1.1 201 Created
{
"report": {
"id": 1016888664,
"name": "A new app report",
"shopify_ql": "SHOW total_sales BY order_id FROM sales SINCE -1m UNTIL today ORDER BY total_sales",
"updated_at": "2021-02-05T21:00:16-05:00",
"category": "custom_app_reports"
}
}
Update an existing report
PUT /admin/api/unstable/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
HTTP/1.1 200 OK
{
"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",
"updated_at": "2021-02-05T21:00:18-05:00",
"category": "custom_app_reports"
}
}
Delete an existing report
DELETE /admin/api/unstable/reports/517154478.json
View Response
HTTP/1.1 200 OK
{
}