report

Collection: reports

To generate a report, send a POST request to the reports resource with the specified parameters detailed in the Properties section.

Report generation happens asynchronously, and may take a number of minutes to prepare. The status value in the report resource indicates whether the report is ready to download.

The report resource represents a previously requested or generated file (typically CSV) summarizing or detailing various store data, such as a customer export, sales summaries, lifetime value, etc.

Once the report is ready (indicated via the status parameter returning "ready"), an fx:download_url link rel will be present with a link to download the report(s). This link will only work for 10 minutes, after which point another link must be generated by making a GET request to the resource or collection. Note that the exact lifespan of this link may change in the future.

Required Scopes

Full store_full_access
Read reporting_read
Write reporting_write

Actions

GET View a report
HEAD Get just the header response
OPTIONS Get a response explaining which HTTP methods are supported

Properties (7)

name String

The type of report generated, indicating the content of the report. "Complete" includes transaction details, summaries, coupon usage, subscription forecasts, and more. "Customers" is for exporting customers to import elsewhere. "Customers_LTV" includes the lifetime value per customer. "Transactions" includes transaction-level data.

completecustomerscustomers_ltvtransactions
version String

In the event a report changes significantly, a new version of the report may be available. Leave this empty to retrieve the latest version, or pass a "1" to request a specific version. In the future, additional versions of each named report may be available.

1
datetime_start String

A timestamp in the YYYY-MM-DD HH:MM:SS format, for the start of the reporting period, for your store's configured timezone. Note that any offset will be ignored, and the datetime passed in will be used as your store's configured timezone.

datetime_end String

Same as datetime_start, but for the end of the report's timeframe. Note that you likely want to pass 23:59:59 as the time portion, or you may inadvertently miss data from the last day of the reporting period.

status String · Read-only

The current status of the report.

queuederrorready
date_created String (nullable) · Read-only

The date this resource was created.

date_modified String (nullable) · Read-only

The date this resource was last modified.

Link Relations (4)

self This Report
fx:download_url GET Download This Report

Only present when the report status is 'ready' and the report file is available for download.

fx:user GET PATCH PUT DELETE This User
https://api.foxycart.com/reports/{id}

Example Representation

{
  "_links": {
    "curies": [
      {
        "name": "fx",
        "href": "https://api.foxycart.com/rels/{rel}",
        "templated": true
      }
    ],
    "self": {
      "href": "https://api.foxycart.com/reports/123",
      "title": "This Report"
    },
    "fx:download_url": {
      "href": "https://api.foxycart.com/download_url",
      "title": "Download This Report"
    },
    "fx:user": {
      "href": "https://api.foxycart.com/users/456",
      "title": "This User"
    }
  },
  "name": "complete",
  "version": "1",
  "datetime_start": "2022-01-01T00:00:00-0800",
  "datetime_end": "2022-01-31T23:59:59-0800",
  "status": "ready",
  "date_created": "2022-03-11T17:38:02-0800",
  "date_modified": "2022-03-11T17:38:38-0800"
}