Report

Version 2019-10

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	`"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 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	`"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/2019-10/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 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": "2020-09-08T13:05:54-04: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": "2020-09-08T13:05:54-04: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": "2020-09-08T13:05:54-04:00",
      "category": "custom_app_reports"
    }
  ]
}

GET /admin/api/2019-10/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/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"
  }
}

POST /admin/api/2019-10/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/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": "2020-09-08T13:23:12-04:00",
    "category": "custom_app_reports"
  }
}

PUT /admin/api/2019-10/reports/{report_id}.json

Updates a report

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": "2020-09-08T13:23:13-04:00",
    "category": "custom_app_reports"
  }
}

DELETE /admin/api/2019-10/reports/{report_id}.json

Deletes a report

Delete an existing report

DELETE /admin/api/2020-07/reports/517154478.json

View Response

HTTP/1.1 200 OK
{
}

Version 2020-01

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	`"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 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	`"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/2020-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 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": "2020-09-08T13:05:54-04: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": "2020-09-08T13:05:54-04: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": "2020-09-08T13:05:54-04:00",
      "category": "custom_app_reports"
    }
  ]
}

GET /admin/api/2020-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/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"
  }
}

POST /admin/api/2020-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/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": "2020-09-08T13:23:12-04:00",
    "category": "custom_app_reports"
  }
}

PUT /admin/api/2020-01/reports/{report_id}.json

Updates a report

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": "2020-09-08T13:23:13-04:00",
    "category": "custom_app_reports"
  }
}

DELETE /admin/api/2020-01/reports/{report_id}.json

Deletes a report

Delete an existing report

DELETE /admin/api/2020-07/reports/517154478.json

View Response

HTTP/1.1 200 OK
{
}

Version 2020-04

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	`"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 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	`"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/2020-04/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 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": "2020-09-08T13:05:54-04: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": "2020-09-08T13:05:54-04: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": "2020-09-08T13:05:54-04:00",
      "category": "custom_app_reports"
    }
  ]
}

GET /admin/api/2020-04/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/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"
  }
}

POST /admin/api/2020-04/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/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": "2020-09-08T13:23:12-04:00",
    "category": "custom_app_reports"
  }
}

PUT /admin/api/2020-04/reports/{report_id}.json

Updates a report

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": "2020-09-08T13:23:13-04:00",
    "category": "custom_app_reports"
  }
}

DELETE /admin/api/2020-04/reports/{report_id}.json

Deletes a report

Delete an existing report

DELETE /admin/api/2020-07/reports/517154478.json

View Response

HTTP/1.1 200 OK
{
}

Version 2020-07 (Latest)

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	`"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 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	`"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/2020-07/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 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": "2020-09-08T13:05:54-04: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": "2020-09-08T13:05:54-04: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": "2020-09-08T13:05:54-04:00",
      "category": "custom_app_reports"
    }
  ]
}

GET /admin/api/2020-07/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/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"
  }
}

POST /admin/api/2020-07/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/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": "2020-09-08T13:23:12-04:00",
    "category": "custom_app_reports"
  }
}

PUT /admin/api/2020-07/reports/{report_id}.json

Updates a report

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": "2020-09-08T13:23:13-04:00",
    "category": "custom_app_reports"
  }
}

DELETE /admin/api/2020-07/reports/{report_id}.json

Deletes a report

Delete an existing report

DELETE /admin/api/2020-07/reports/517154478.json

View Response

HTTP/1.1 200 OK
{
}

Version 2020-10 (Release candidate)

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	`"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 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	`"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/2020-10/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 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": "2020-09-08T13:05:54-04: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": "2020-09-08T13:05:54-04: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": "2020-09-08T13:05:54-04:00",
      "category": "custom_app_reports"
    }
  ]
}

GET /admin/api/2020-10/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/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"
  }
}

POST /admin/api/2020-10/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/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": "2020-09-08T13:23:12-04:00",
    "category": "custom_app_reports"
  }
}

PUT /admin/api/2020-10/reports/{report_id}.json

Updates a report

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": "2020-09-08T13:23:13-04:00",
    "category": "custom_app_reports"
  }
}

DELETE /admin/api/2020-10/reports/{report_id}.json

Deletes a report

Delete an existing report

DELETE /admin/api/2020-07/reports/517154478.json

View Response

HTTP/1.1 200 OK
{
}