The REST Admin API is a legacy API as of October 1, 2024. All apps and integrations should be built with the GraphQL Admin API. For details and migration steps, visit our migration guide.

Anchor to section titled 'undefined'

Report

Requires reports access scope.

Important

As of REST API 2024-04, the Reports resource has been removed.

See the Changelog entry.

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.

Was this section helpful?
#Endpoints
Anchor to section titled 'The Report resource'

The Report resource

Properties
category
deprecated
The category for the report. When you create a report, the API will return custom_app_reports.
id
deprecated
The unique numeric identifier for the report.
name
deprecated
The name of the report. Maximum length: 255 characters.
shopify_ql
deprecated
The ShopifyQL query that generates the report. See Shopify Query Language.
updated_at
deprecated
The date and time (ISO 8601) when the report was last modified.
Was this section helpful?
{}The Report resource
{
  "category": "custom_app_reports",
  "id": 517154478,
  "name": "My App Report",
  "shopify_ql": "SHOW total_sales BY order_id FROM sales SINCE -1m UNTIL today ORDER BY total_sales",
  "updated_at": "2008-02-01T19:00:00-05:00"
}
Anchor to section titled 'POST request, Creates a new report'

post
Creates a new report
deprecated

Creates a new report
Anchor to section titled 'Parameters of Creates a new report'

Parameters

api_version
string
required
name
The name of the report. Maximum length: 255 characters.
shopify_ql
The ShopifyQL the report will query.
Was this section helpful?
Anchor to section titled 'Examples of Creates a new report'

Examples

Request body
report
Report resource
Was this section helpful?
post
/admin/api/2024-01/reports.json
Copy
curl -d '{"report":{"name":"A new app report","shopify_ql":"SHOW total_sales BY order_id FROM sales SINCE -1m UNTIL today ORDER BY total_sales"}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2024-01/reports.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}Response
JSON
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": "2024-09-19T10:12:46-04:00",
    "category": "custom_app_reports"
  }
}
Anchor to section titled 'GET request, Retrieves a list of reports'

get
Retrieves a list of reports
deprecated

Retrieves a list of reports. Note: This endpoint implements pagination by using links that are provided in the response header. To learn more, refer to Make paginated requests to the REST Admin API.
Anchor to section titled 'Parameters of Retrieves a list of reports'

Parameters

api_version
string
required
fields
A comma-separated list of fields to include in the response.
ids
A comma-separated list of report IDs.
limit
≤ 250
default 50
The amount of results to return.
since_id
Restrict results to after the specified ID.
updated_at_max
Show reports last updated before date. (format: 2014-04-25T16:15:47-04:00)
updated_at_min
Show reports last updated after date. (format: 2014-04-25T16:15:47-04:00)
Was this section helpful?
Anchor to section titled 'Examples of Retrieves a list of reports'

Examples

Query parameters
sinceid=123
Restrict results to after the specified ID.
Was this section helpful?
get
/admin/api/2024-01/reports.json?sinceid=123
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-01/reports.json?since_id=123" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
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": "2024-09-19T10:10:57-04:00",
      "category": "custom_app_reports"
    }
  ]
}
Anchor to section titled 'GET request, Retrieves a single report'

get
Retrieves a single report
deprecated

Retrieves a single report created by your app
Anchor to section titled 'Parameters of Retrieves a single report'

Parameters

api_version
string
required
report_id
string
required
fields
A comma-separated list of fields to include in the response.
Was this section helpful?
Anchor to section titled 'Examples of Retrieves a single report'

Examples

Path parameters
reportid=517154478
string
required
Was this section helpful?
get
/admin/api/2024-01/reports/517154478.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-01/reports/517154478.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
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"
  }
}
Anchor to section titled 'PUT request, Updates a report'

put
Updates a report
deprecated

Updates a report
Anchor to section titled 'Parameters of Updates a report'

Parameters

api_version
string
required
report_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Updates a report'

Examples

Path parameters
reportid=517154478
string
required
Request body
report
Report resource
Was this section helpful?
put
/admin/api/2024-01/reports/517154478.json
Copy
curl -d '{"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"}}' \
-X PUT "https://your-development-store.myshopify.com/admin/api/2024-01/reports/517154478.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}Response
JSON
HTTP/1.1 200 OK
{
  "report": {
    "name": "Changed Report Name",
    "shopify_ql": "SHOW total_sales BY order_id FROM sales SINCE -12m UNTIL today ORDER BY total_sales",
    "id": 517154478,
    "updated_at": "2024-09-19T10:12:47-04:00",
    "category": "custom_app_reports"
  }
}
Anchor to section titled 'DELETE request, Deletes a report'

del
Deletes a report
deprecated

Deletes a report
Anchor to section titled 'Parameters of Deletes a report'

Parameters

api_version
string
required
report_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Deletes a report'

Examples

Path parameters
reportid=517154478
string
required
Was this section helpful?
del
/admin/api/2024-01/reports/517154478.json
Copy
curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2024-01/reports/517154478.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{}