# Exporting resources
Commerce Layer lets you export resources in **JSON** (default) or **CSV** formats. To do that, you need to create a new [export resource](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/exports), specify the `resource_type` you want to export, and the `format` of the exported file. Optionally, you can also specify the relationships you want to [include](#including-associations), apply some [filters](#filtering-exported-data) to narrow the exported data, and decide to [skip](#skipping-redundant-attributes) some redundant attributes.
{% hint style="info" %}
To export a CSV list you need to set the `format` attribute to `csv`. Otherwise, if the format is not specified, your data will be exported using the default format (JSON).
{% endhint %}
The process is **asynchronous** and you can poll the `status` attribute to [check the export progress](#checking-the-export-status). As soon as an export is created you can check the number of items that are going to be exported by inspecting the `records_count` attribute. If you try to export a resource with `records_count = 0`, an error is returned.
{% hint style="info" %}
Resource relationships are exported by default with their IDs, appending the `_id` suffix to the name of the related resource (e.g. `"price_list_id": "xYZkjABcde"`). Some relationships can also be exported as a nested object if specified as valid [included associations](#including-associations).
{% endhint %}
## Attachment URL
Once the export process is completed, the results are compressed ([gzip](https://www.gzip.org/)) and uploaded to an external storage service (currently [Amazon S3](https://aws.amazon.com/s3/)). You can download the exported data using the link exposed in the `attachment_url` attribute.
{% hint style="info" %}
External storage service URLs expire in **5 minutes**. You need to uncompress (`gunzip`) the file in order to read the data back. If the exported data URL is expired you can just [fetch the completed export](#checking-the-export-status) to get a new working one.
{% endhint %}
## Export limits
### Export size
There is **no limit** on export size. However, very large jobs may take several hours to complete, as the data is exported in multiple rounds, prioritizing reliability over speed. You can monitor the current progress of the export by checking the export's `progress` attribute. Once a job round has finished, you can also estimate the completion time by inspecting the `estimated_completion_at` attribute, which is updated after each round.
### Concurrent exports
The maximum number of concurrent exports (i.e. exports whose status is `pending` or `in_progess`) allowed per organization is **10**.
{% hint style="info" %}
If you absolutely need to export any of the [supported resources](#supported-resources) in one go, overriding the API limits above, you can leverage the power of our [CLI export plugin](https://github.com/commercelayer/commercelayer-cli-plugin-exports/) ([see example](#exporting-more-than-10k-orders-using-the-cli)). Alternatively, you can also perform a [search query](https://app.gitbook.com/s/ASSiAvbL4nFnkl8plQy2/getting-started/queries/search) using our [Metrics API](https://app.gitbook.com/o/-Lfu_B3DKew-kvoEWzTk/s/ASSiAvbL4nFnkl8plQy2/) (at the moment limited to [orders](https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/orders), [carts](https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/carts), and [returns](https://app.gitbook.com/s/lhTYC557IzGiJNS84RKD/resources/returns)).
{% endhint %}
## Supported resources
At the moment, exports are available for almost all of the resources [exposed via API](https://app.gitbook.com/o/-Lfu_B3DKew-kvoEWzTk/s/RWJeylueWkzLadK710XZ/). Please find some examples of how to export them [here below](#examples).
{% hint style="info" %}
With very few exceptions (e.g. shipments, transactions, customer payment sources, etc.), exported outputs (both in JSON or CSV format) can be used as `inputs` for the [imports API](https://docs.commercelayer.io/core/importing-resources). If you're using the *export + import* features to duplicate your dataset records (e.g. to migrate your test data to your live [environment](https://docs.commercelayer.io/core/api-specification#environments)) you may need to [skip](#skipping-redundant-attributes) some redundant attributes. Specifically, if you want to export resources from an organization and import them into a different one, make sure to set the export's `dry_data` attribute to `true` in order to avoid ID conflicts. In that case, we also suggest not to use [fields](#selecting-fields) when exporting the data you plan to re-import elsewhere (use [includes](#including-associations) instead).
{% endhint %}
{% content-ref url="importing-resources" %}
[importing-resources](https://docs.commercelayer.io/core/importing-resources)
{% endcontent-ref %}
## Including associations
It's possible to include one or more relationships of the exported resource using the `includes` attribute. Relationships will be exported as an object if singular (`has_one` or `belongs_to`), or as an array of objects if multiple (`has_many`) — check Commerce Layer API [data model](https://commercelayer.io/docs/data-model/) for more information on how resources relate to each other.
{% hint style="warning" %}
If you use the CSV format to export your data the output will have the relationship attributes **flattened** together with the parent resource ones. As a result, you'll find the resource attributes repeated on multiple lines, with relationship ones appended at the end. When exporting tags together with a tagged resource the cells belonging to the `tags.id` and `tags.name` columns contain a string with the list of IDs/names, comma separated. In general, using CSV is fine for simple exports (resources with a few attributes and no relationship included), otherwise we strongly recommend using JSON.
{% endhint %}
When including associations, multiple levels of relationships are supported. You just need to append the more specific using the use the [dot notation](https://idratherbewriting.com/learnapidoc/docapis_diving_into_dot_notation.html) `.` (e.g. [line item options for orders](#exporting-a-list-of-orders), or [price tiers for SKUs](#exporting-a-filtered-list-of-skus-with-prices-price-tiers-stock-items-and-tax-categories-json)).
{% hint style="warning" %}
CSV `format` supports only **one level** of relationship (e.g. if you try to include `line_items.line_item_options` when exporting orders, only the line items will be exported).
{% endhint %}
### Supported associations
All of the valid resource relationships can be included when exporting. Please refer to the specific resource page in the [Core API reference](https://app.gitbook.com/o/-Lfu_B3DKew-kvoEWzTk/s/RWJeylueWkzLadK710XZ/) to check which relationships you can include when exporting it.
{% hint style="warning" %}
In case you specify an invalid include for the exported resource, an error is raised before creating (and starting) the export.
{% endhint %}
## Selecting fields
When exporting resources, you can select the resource fields to be exported in advance by specifying the `fields` attribute as an array of values.
For the main exported resource you can pass fields using the plain attribute names. For any related association's attribute use the [dot notation](https://idratherbewriting.com/learnapidoc/docapis_diving_into_dot_notation.html) (the same used when [including associations](#including-associations)), i.e. `.` followed by the field name.
{% hint style="info" %}
If you want to export all the fields of a resource, use the asterisk `*` (works both for the main and related resources).
{% endhint %}
For example, if you want to export SKUs with their code and name plus some specific fields of the associated prices and stock items and all the fields of the associated shipping category, use a `field` array like this:
```json
...
"fields": [
"code",
"name",
"prices.amount_cents",
"prices.price_list.name",
"stock_items.stock_location.code",
"shipping_category.*"
...
]
```
{% hint style="warning" %}
Some attributes which are potentially sensible (e.g. any kind of credentials) will not be included in the exported file also if you explicitly specify them in the `fields` array.
{% endhint %}
### Fields vs. includes
Specifying `includes` is completely redundant when using `fields` since any association's related attribute listed among the fields automatically includes the related resource. This also means that:
* If you specify a field using an invalid related association, an error is raised before creating (and starting) the export.
* If you include an association that has no corresponding related field, its data will not be exported.
{% hint style="info" %}
As a general rule of thumb, use `includes` when you want to export all the fields of the included resource and use `fields` when you want to export specific fields of the resource only.
{% endhint %}
## Filtering exported data
When exporting resources, you can fine-tune the data to be exported by applying some filters (both to the resources and their relationships) using the `filters` attribute:
```json
...
"filters": {
"{{predicate}}": {{value}},
...
}
```
To compose the filter predicate you just need to follow the [same syntax](https://docs.commercelayer.io/core/filtering-data) you use when filtering a collection of resources — `{{attributes}}_{{matcher}}`. You must specify filtering rules as a valid JSON object. List values for the `*_in` matcher need to be expressed as arrays (as in [this example](#exporting-a-filtered-list-of-bundles-with-sku-lists-and-sku-list-items-csv)).
{% content-ref url="filtering-data" %}
[filtering-data](https://docs.commercelayer.io/core/filtering-data)
{% endcontent-ref %}
## Skipping redundant attributes
You might want to compact exported data by removing some redundant attributes from the final JSON or CSV output. To do that, set the `dry_data` specific boolean attribute to `true` — the following attributes and values will be skipped:
* The main resource IDs.
* The timestamp attributes (`created_at` and `updated_at`).
* Any empty or `null` attribute value (working when exporting in the JSON format only).
* All the formatted amounts other than cents (e.g. for prices, orders, etc.).
## Interrupting and restarting
You can interrupt an in-progress export at any time by updating it with the `_interrupt` trigger attribute. The export will stop at the end of the current round, recording the last resource processed and preserving information about the remaining data.
To restart an interrupted export, update it passing the `_start` trigger attribute. Processing will resume from the point of interruption, and the `estimated_completion_at` attribute will be recalculated based on the time of the restart.
{% hint style="warning" %}
The resources to be exported are automatically capped at the timestamp when the export was created. This ensures consistency by preventing the dataset from growing in size or simply changing during the process (e.g. if a new import begins while the export is still running).
{% endhint %}
## Examples
### Exporting some fields of a filtered list of addresses (JSON)
{% tabs %}
{% tab title="Request" %}
The following request creates an export of a list of addresses in `JSON` format, filtered by country code and city, fetching just the `full_name` and `full_address` fields:
```shell
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/exports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "exports",
"attributes": {
"resource_type": "addresses",
"fields": [ "full_name", "full_address" ],
"filters": {
"country_code_eq": "IT",
"city_in": [ "Rome", "Milan", "Prato" ]
}
}
}
}'
```
{% endtab %}
{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created export object:
```json
{
"data": {
"id": "PmjlkIJzRA",
"type": "exports",
"links": {...},
"attributes": {
"resource_type": "addresses",
"format": "json",
"status": "pending",
"includes": [],
"fields": ["full_name", "full_address"],
"filters": {"country_code_eq": "IT", "city_in": ["Rome", "Milan", "Prato"]},
"dry_data": true,
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"records_count": 8765,
"attachment_url": null,
"errors_log": {},
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": {...}
}
}
```
{% endtab %}
{% endtabs %}
### Exporting a filtered list of bundles with SKU lists and SKU list items (CSV)
{% tabs %}
{% tab title="Request" %}
The following request creates an export of a list of bundles and their associated SKU lists and SKU list items in CSV format, filtered by SKU list name:
```shell
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/exports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "exports",
"attributes": {
"resource_type": "bundles",
"format": "csv",
"includes": [ "sku_list", "sku_list_items" ],
"filters": {
"sku_list_name_in": [ "6 pack", "12 pack" ]
}
}
}
}'
```
{% endtab %}
{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created export object:
```json
{
"data": {
"id": "PmjlkIJzRA",
"type": "exports",
"links": {...},
"attributes": {
"resource_type": "bundles",
"format": "csv",
"status": "in_progress",
"includes": ["sku_list", "sku_list_items"],
"fields": [],
"filters": {"sku_list_name_in": ["six pack", "12 pack"]},
"dry_data": null,
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"records_count": 43,
"attachment_url": null,
"errors_log": {},
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": {...}
}
}
```
{% endtab %}
{% endtabs %}
### Exporting a list of coupons (JSON)
{% tabs %}
{% tab title="Request" %}
The following request creates an export of a list of coupons in JSON format, skipping the redundant attributes:
```shell
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/exports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "exports",
"attributes": {
"resource_type": "coupons",
"dry_data": true
}
}
}'
```
{% endtab %}
{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created export object:
```json
{
"data": {
"id": "PmjlkIJzRA",
"type": "exports",
"links": {...},
"attributes": {
"resource_type": "coupons",
"format": "json",
"status": "in_progress",
"includes": [],
"fields": [],
"filters": {},
"dry_data": true,
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"records_count": 9876,
"attachment_url": null,
"errors_log": {},
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": {...}
}
}
```
{% endtab %}
{% endtabs %}
### Exporting some fields a filtered list of customer addresses with addresses and customers (JSON)
{% tabs %}
{% tab title="Request" %}
The following request creates an export of a list of customer addresses in JSON format, filtered by customer's email, fetching just the associated customer `email` and address `full_address` fields:
```shell
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/exports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "exports",
"attributes": {
"resource_type": "customer_addresses",
"format": "json",
"fields": [ "address.full_address", "customer.email" ],
"filters": {
"customer_email_end": ".com"
}
}
}
}'
```
{% endtab %}
{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created export object:
```json
{
"data": {
"id": "PmjlkIJzRA",
"type": "exports",
"links": {...},
"attributes": {
"resource_type": "customer_addresses",
"format": "json",
"status": "in_progress",
"includes": ["address", "customer"],
"fields": ["address.full_address", "customer.email"],
"filters": {"customer_email_end": ".com"},
"dry_data": true,
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"records_count": 254,
"attachment_url": null,
"errors_log": {},
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": {...}
}
}
```
{% endtab %}
{% endtabs %}
### Exporting a filtered list of customer subscriptions with customers (CSV)
{% tabs %}
{% tab title="Request" %}
The following request creates an export of a list of customer subscriptions and their associated customers in CSV format filtered by email:
```shell
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/exports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "exports",
"attributes": {
"resource_type": "customer_subscriptions",
"format": "csv",
"includes": [ "customer" ],
"filters": {
"customer_email_matches": "%gmail.com"
}
}
}
}'
```
{% endtab %}
{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created export object:
```json
{
"data": {
"id": "PmjlkIJzRA",
"type": "exports",
"links": {...},
"attributes": {
"resource_type": "customer_subscriptions",
"format": "csv",
"status": "in_progress",
"includes": ["customer"],
"fields": [],
"filters": {"customer_email_matches": "%gmail.com"},
"dry_data": null,
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"records_count": 345,
"attachment_url": null,
"errors_log": {},
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": {...}
}
}
```
{% endtab %}
{% endtabs %}
### Exporting some fields of a filtered list of customers with customer subscriptions (JSON)
{% tabs %}
{% tab title="Request" %}
The following request creates an export of a list of customers in JSON format filtered by email, fetching all the customer attributes and just the customer subscription `reference` field:
```shell
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/exports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "exports",
"attributes": {
"resource_type": "customers",
"format": "json",
"fields": [ "*", "customer_subscriptions.reference" ],
"filters": {
"email_end": ".com"
}
}
}
}'
```
{% endtab %}
{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created export object:
```json
{
"data": {
"id": "PmjlkIJzRA",
"type": "exports",
"links": {...},
"attributes": {
"resource_type": "customers",
"format": "json",
"status": "in_progress",
"includes": ["customer_subscriptions"],
"fields": ["*", "customer_subscriptions.reference"],
"filters": {"email_end": ".com"},
"dry_data": true,
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"records_count": 254,
"attachment_url": null,
"errors_log": {},
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": {...}
}
}
```
{% endtab %}
{% endtabs %}
### Exporting a filtered list of gift cards (CSV)
{% tabs %}
{% tab title="Request" %}
The following request creates an export of a list of gift cards in CSV format, filtered by the date and time at which they were created:
```shell
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/exports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "exports",
"attributes": {
"resource_type": "gift_cards",
"format": "csv",
"filters": {
"created_at_gteq": "2018-01-01T12:00:00.000Z"
}
}
}
}'
```
{% endtab %}
{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created export object:
```json
{
"data": {
"id": "PmjlkIJzRA",
"type": "exports",
"links": {...},
"attributes": {
"resource_type": "gift_cards",
"format": "csv",
"status": "in_progress",
"includes": [],
"fields": [],
"filters": {"created_at_gteq": "2018-01-01T12:00:00.000Z"},
"dry_data": null,
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"records_count": 349,
"attachment_url": null,
"errors_log": {},
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": {...}
}
}
```
{% endtab %}
{% endtabs %}
### Exporting a filtered list of orders with customer, addresses, line items, line item options, payment method, and refunds (JSON)
{% tabs %}
{% tab title="Request" %}
The following request creates an export of a list of orders dry data with the associated customer, addresses, line items, line item options, payment method, and refunds in JSON format, filtered by status, country code, and the date and time at which they were placed:
```shell
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/exports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "exports",
"attributes": {
"resource_type": "orders",
"includes": [
"customer",
"shipping_address",
"billing_address",
"line_items.line_item_options",
"payment_method",
"refunds"
],
"filters": {
"status_in": [ "placed", "approved" ],
"placed_at_gteq": "2018-01-01T12:00:00.000Z",
"country_code_eq": "IT"
},
"dry_data": true
}
}
}'
```
{% endtab %}
{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created export object:
```json
{
"data": {
"id": "PmjlkIJzRA",
"type": "exports",
"links": {...},
"attributes": {
"resource_type": "orders",
"format": "json",
"status": "in_progress",
"includes": ["customer", "shipping_address", "billing_address", "line_items.line_item_options", "payment_method", "refunds"],
"fields": [],
"filters": {"status_in": ["placed", "approved"], "placed_at_gteq": "2018-01-01T12:00:00.000Z", "country_code_eq": "IT"},
"dry_data": true,
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"records_count": 6499,
"attachment_url": null,
"errors_log": {},
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": {...}
}
}
```
{% endtab %}
{% endtabs %}
### Exporting a filtered list of order subscriptions with order subscription items and customer payment source (JSON)
{% tabs %}
{% tab title="Request" %}
The following request creates an export of a list of order subscriptions with the associated order subscription items and customer payment source in JSON format (skipping the redundant attributes), filtered by customer email:
```shell
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/exports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "exports",
"attributes": {
"resource_type": "order_subscriptions",
"format": "json",
"includes": [ "order_subscription_items", "customer_payment_source" ],
"filters": {
"customer_email_eq": "george@gmail.com"
},
"dry_data": true
}
}
}'
```
{% endtab %}
{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created export object:
```json
{
"data": {
"id": "PmjlkIJzRA",
"type": "exports",
"links": {...},
"attributes": {
"resource_type": "order_subscriptions",
"format": "json",
"status": "in_progress",
"includes": ["order_subscription_items", "customer_payment_source"],
"fields": [],
"filters": {"customer_email_eq": "george@gmail.com"},
"dry_data": true,
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"records_count": 254,
"attachment_url": null,
"errors_log": {},
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": {...}
}
}
```
{% endtab %}
{% endtabs %}
### Exporting some fields of a filtered list of prices with price tiers (CSV)
{% tabs %}
{% tab title="Request" %}
The following request creates an export of a list of prices with associated SKUs and price tiers in CSV format, fetching just the price's `amount_cents` and the associated SKU's `code`, price tier's `type` and `price_amount_cents` fields, filtered by the associated price list's currency code:
```shell
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/exports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "exports",
"attributes": {
"resource_type": "prices",
"format": "csv",
"fields": [ "amount_cents", "sku.code", "price_tiers.type", "price_tiers.price_amount_cents" ],
"filters": {
"price_list_currency_code_eq": "USD"
},
"dry_data": true
}
}
}'
```
{% endtab %}
{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created export object:
```json
{
"data": {
"id": "PmjlkIJzRA",
"type": "exports",
"links": {...},
"attributes": {
"resource_type": "prices",
"format": "csv",
"status": "in_progress",
"includes": ["sku", "price_tiers"],
"fields": ["amount_cents", "sku.code", "price_tiers.type", "price_tiers.price_amount_cents"],
"filters": {"price_list_currency_code_eq": "USD"},
"dry_data": true,
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"records_count": 3456,
"attachment_url": null,
"errors_log": {},
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": {...}
}
}
```
{% endtab %}
{% endtabs %}
### Exporting a filtered list of SKU lists with SKU list items (JSON)
{% tabs %}
{% tab title="Request" %}
The following request creates an export of a list of SKU lists with associated SKU list items in JSON format, filtered SKU list type (manual):
```shell
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/exports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "exports",
"attributes": {
"resource_type": "sku_lists",
"includes": [ "sku_list_items" ],
"filters": {
"manual_true": true
}
}
}
}'
```
{% endtab %}
{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created export object:
```json
{
"data": {
"id": "PmjlkIJzRA",
"type": "exports",
"links": {...},
"attributes": {
"resource_type": "sku_lists",
"format": "json",
"status": "in_progress",
"includes": ["sku_list_items"],
"fields": [],
"filters": {"manual_true": true},
"dry_data": null,
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"records_count": 3456,
"attachment_url": null,
"errors_log": {},
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": {...}
}
}
```
{% endtab %}
{% endtabs %}
### Exporting a filtered list of SKUs with prices, price tiers, stock items, and tax categories (JSON)
{% tabs %}
{% tab title="Request" %}
The following request creates an export with a list of SKUs, with the associated prices, price tiers, stock items, and tax categories in JSON format (skipping the redundant attributes), filtered by SKU name:
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/exports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "exports",
"attributes": {
"resource_type": "skus",
"includes": [ "prices.price_tiers", "stock_items", "tax_categories" ],
"filters": {
"name_cont": "FW"
},
"dry_data": true
}
}
}'
{% endtab %}
{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created export object:
```json
{
"data": {
"id": "PmjlkIJzRA",
"type": "exports",
"links": {...},
"attributes": {
"resource_type": "skus",
"format": "json",
"status": "in_progress",
"includes": [ "prices.price_tiers", "stock_items", "tax_categories" ],
"fields": [],
"filters": { "name_cont": "FW" },
"dry_data": true,
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"records_count": 2345,
"attachment_url": null,
"errors_log": {},
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": {...}
}
}
```
{% endtab %}
{% endtabs %}
### Exporting some fields of a filtered list of stock items with SKUs and stock location (CSV)
{% tabs %}
{% tab title="Request" %}
The following request creates an export of a list of stock items and the associated SKUs and stock location in CSV format (skipping the redundant attributes), filtered by stock item quantity, fetching just the stock item's `quantity`, and the associated SKU's `code` and stock location's `name` fields:
```shell
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/exports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "exports",
"attributes": {
"resource_type": "stock_items",
"format": "csv",
"fields": [ "quantity", "sku.code", "stock_location.name" ],
"filters": {
"quantity_gteq": 1
},
"dry_data": true
}
}
}'
```
{% endtab %}
{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created export object:
```json
{
"data": {
"id": "PmjlkIJzRA",
"type": "exports",
"links": {...},
"attributes": {
"resource_type": "stock_items",
"format": "csv",
"status": "in_progress",
"includes": ["sku", "stock_location"],
"fields": ["quantity", "sku.code", stock_location.name],
"filters": {"quantity_gteq": 1},
"dry_data": true,
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"records_count": 4567,
"attachment_url": null,
"errors_log": {},
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": {...}
}
}
```
{% endtab %}
{% endtabs %}
### Exporting some fields of a filtered list of stock transfers with SKUs and stock locations (CSV)
{% tabs %}
{% tab title="Request" %}
The following request creates an export of a list of stock transfers (filtered by their quantity) with the associated stock locations and SKUs in CSV format (skipping the redundant attributes), fetching just the stock transfer's `quantity`, the origin and destination stock location `name`, and all the SKU's fields:
```shell
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/exports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "exports",
"attributes": {
"resource_type": "stock_transfers",
"format": "csv",
"fields": [ "quantity", "sku.*", "origin_stock_location.name, "destination_stock_location.name" ],
"filters": {
"quantity_gteq": 1
},
"dry_data": true
}
}
}'
```
{% endtab %}
{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created export object:
```json
{
"data": {
"id": "PmjlkIJzRA",
"type": "exports",
"links": {...},
"attributes": {
"resource_type": "stock_transfers",
"format": "csv",
"status": "in_progress",
"includes": ["sku", "origin_stock_location", "destination_stock_location"],
"fields": ["quantity", "sku.*", "origin_stock_location.name, "destination_stock_location.name"],
"filters": {"quantity_gteq": 1},
"dry_data": true,
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"records_count": 4567,
"attachment_url": null,
"errors_log": {},
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": {...}
}
}
```
{% endtab %}
{% endtabs %}
### Exporting all the tags (CSV)
{% tabs %}
{% tab title="Request" %}
The following request creates an export of all the tags you created for your organization in CSV format:
```shell
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/exports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "exports",
"attributes": {
"resource_type": "tags",
"format": "csv"
}
}
}'
```
{% endtab %}
{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created export object:
```json
{
"data": {
"id": "WoDOghDQlz",
"type": "exports",
"links": { ... },
"attributes": {
"resource_type": "tags",
"format": "csv",
"status": "in_progress",
"includes": [],
"fields": [],
"filters": {},
"dry_data": null,
"started_at": "2018-01-01T12:00:00.000Z",
"completed_at": null,
"interrupted_at": null,
"records_count": 123,
"attachment_url": null,
"errors_log": {},
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"relationships": { ... },
"meta": { ... }
}
}
```
{% endtab %}
{% endtabs %}
### Exporting some fields of all the SKUs tagged with at least one of two tags (JSON)
{% tabs %}
{% tab title="Request" %}
The following request creates an export of all the SKU associated with the tag identified by the "geJmexflJQ" ID or by the "XEqZPxfPam" ID, fetching just the `code` and tag `name` fields, in JSON format:
```shell
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/exports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "exports",
"attributes": {
"resource_type": "skus",
"fields": [ "code", "tags.name" ],
"filters": {
"tags_id_in": [ "geJmexflJQ", "XEqZPxfPam" ]
}
}
}
}'
```
{% endtab %}
{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created export object:
```json
{
"data": {
"id": "wlyGbhDNjM",
"type": "exports",
"links": { ... },
"attributes": {
"resource_type": "skus",
"format": "json",
"status": "in_progress",
"includes": ["tags"],
"fields": ["code", "tags.name"],
"filters": {
"tags_id_in": ["geJmexflJQ", "XEqZPxfPam"]
},
"dry_data": null,
"started_at": "2018-01-01T12:00:00.473Z",
"completed_at": null,
"interrupted_at": null,
"records_count": 234,
"attachment_url": null,
"errors_log": {},
"created_at": "2018-01-01T12:00:00.463Z",
"updated_at": "2018-01-01T12:00:00.472Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"relationships": { ... },
"meta": { ... }
}
}
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
When filtering a list of tagged resources by tag(s) the only allowed predicates are `tags_id_in` and `tags_id_not_in`.
{% endhint %}
### Exporting more than 10K orders using the CLI
{% tabs %}
{% tab title="CLI command" %}
The following command exports all the approved orders whose amount is over $1000 (including the associated customer, line items, and tags) in JSON format into a single file and saves it to a specified path:
```
commercelayer exports:all -t orders -i customer,line_items,tags -w status_eq=approved -w currency_code_eq=USD -w total_amount_cents_gt=100000 -X ./exports/orders
```
{% endtab %}
{% tab title="Success message" %}
On success, the CLI prompts this message on your terminal, separating the single exports and showing some basic information about the completed processes:
Exporting 15000 orders ...
✓ Export 1 completed
✓ Export 2 completed
Export of 15000 orders completed.
Exported file saved to ./exports/orders.json
{% endtab %}
{% endtabs %}
## Checking the export status
You can inspect the status of a specific export by fetching the single export by ID and looking at the `status` attribute.
{% tabs %}
{% tab title="Request" %}
```shell
curl -g -X GET \
'https://yourdomain.commercelayer.io/api/exports/PmjlkIJzRA' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token'
```
{% endtab %}
{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning the single export object:
```json
{
"data": {
"id": "PmjlkIJzRA",
"type": "exports",
"links": {...},
"attributes": {
"resource_type": "stock_items",
"format": "csv",
"status": "completed",
"includes": ["sku"],
"fields": [],
"filters": {"quantity_gteq": 1},
"dry_data": true,
"started_at": "2018-01-01T12:00:00.000Z",
"completed_at": "2018-01-01T12:03:00.000Z",
"interrupted_at": null,
"records_count": 4567,
"attachment_url": "http://cl_exports.s3.amazonaws.com/",
"errors_log": {},
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": {...}
}
}
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
When you create an export, it tries immediately to start the exporting process, entering the `in_progress` status. In case the async queue is saturated, the export remains `pending` until it gets a chance to be processed.
{% endhint %}
{% hint style="warning" %}
If an export gets stuck in the `in_progress` status for any reason, you can mark it as `interrupted` by patching it with the `_interrupt` trigger attribute set to `true`. In case an export fails instead, it is automatically moved to the `interrupted` status and the `errors_log` attribute gets filled with the runtime error that caused the interruption.
{% endhint %}
## Webhooks for exports
You can also leverage Commerce Layer real-time webhooks mechanism, listen to `exports.create`, `exports.start`, `exports.complete`, `exports.interrupt`, or `exports.destroy` and react properly.
{% content-ref url="real-time-webhooks" %}
[real-time-webhooks](https://docs.commercelayer.io/core/real-time-webhooks)
{% endcontent-ref %}