Export

How to perform an export query and how it works

Exports are a special kind of search query where the result data are converted into a tabular format (CSV). When performing an export query on the Metrics API endpoint, you get in the response a CSV file (text/csv) returned inline, containing the requested fields (sorted and filtered) of the actual records that match the query.

The maximum size allowed for the results of an export query is 100K records. Export queries matching a higher number of records will return a 422 UNPROCESSABLE ENTITY error.

Request

To perform an export query, send a POST request to the /{{resource_name}}/export endpoint specifying the query keys and filter parameters:

{
  "search": {
    "sort": "...",
    "sort_by": "...",
    "fields": [ ... ]
  },
  "filter": { ... }
}

Query keys

Key	Type	Required	Description	Values
sort	String		The way you want the results of the query to be sorted.	One of asc or desc (default is desc).
sort_by	String		The date field you want the results of the query sorted by.	The available values for this key depend on the resource you're searching (see orders, returns, or carts for the related lists). Default is {{resource_name}}.current_date (i.e. the datetime of the resource's latest status change).
fields	Array		The list of fields you want to be exported for each record.	The available values for this key depend on the resource you're searching (see orders, returns, or carts for the related lists). If empty, default fields will be exported.

Allowed and default fields

Unlike in the search query:

• Only the root resource (i.e. order or return) and single-level references are allowed (e.g. no line items or return line items).

• The fields array can be empty. If so, some default fields will be exported (see example). The list of default fields depends on the resource you're exporting (see orders, returns, or carts for more information).

• No meta information is returned.

• No pagination is available for the results (all the records will be exported up to the maximum limit allowed).

Response

The response of an export query is a plain CSV file (text/csv) returned inline and containing a maximum of 100K records, sorted by the date field specified in the sort_by key. For each record, all the fields requested in the fields array (if specified) are exported.

In case of multiple tags for the same resource, tags.name and tags.id will generate space-separated values within the related table column (see example).

Examples

The following examples will focus on the query part of the request. No specific filter will be defined (i.e. all the results will be filtered by the default filter). See the use cases section for more complex combinations of queries and filters.

Default export

Request

The following request performs an export query with an empty body to export as CSV the default fields of the matching orders, sorted by the default date field (i.e. the order's latest status change):

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.co/metrics/orders/export' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d ''

Response

Exporting specific fields

Request

The following request performs an export query to get information about the orders ID, last time of update, the associated customer ID and email, and the orders tags name (if any), sorted in ascending order by the time when they were updated:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.co/metrics/orders/export' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "search": {
      "sort": "asc",
      "sort_by": "order.updated_at",
      "fields": [
        "order.id",
        "order.updated_at",
        "customer.id",
        "customer.email",
        "tags.name"
      ]
    }
  }'

Response