Exporting resources

Getting started API reference How-tos Changelog
Search…
Exporting resources
How to bulk export resources and their relationships
Commerce Layer lets you export resources in JSON (default) or CSV formats. To do that, you need to create a new export resource, 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, apply some filters to narrow the exported data, and decide to skip some redundant attributes.
To import 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).
The process is asynchronous and you can poll the status attribute to check the export progress. 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.
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.
Attachment URL
Once the export process is completed, the results are compressed (gzip) and uploaded to an external storage service (currently Amazon S3). You can download the exported data using the link exposed in the attachment_url attribute.
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 to get a new working one.
Export limits
Maximum export size
Exports are subject to some soft limits: the records_count must be a maximum of 10000 records, otherwise the export will be rejected at the time of creation.
Concurrent exports
The maximum number of concurrent exports (i.e. exports whose status is pending or in_progess) allowed per organization is 10.
Supported resources
At moment, exports are available for the following resources (more to come):
Addresses
Bundles
Coupons
Customer subscriptions
Customers
Gift cards
Line items
Orders
Price tiers
Prices
Shipping categories
SKU list items
SKU lists
SKU options
SKUs
Stock items
Tax categories
Please find some examples of how to import them here below.
Exported outputs (both in JSON or CSV format) can be used as inputs for the imports API. If you're using the export + import features to duplicate your dataset records (e.g. to migrate your test data to your live environment) you may need to skip IDs, timestamps, and empty attributes.
Importing resources
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 for more information on how resources relate to each other.
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. That's why, in general, using CSV is fine for simple exports (resources with a few attributes and no relationship included), otherwise we strongly recommend using JSON.
When including associations, multiple levels of relationships are supported. You just need to append the more specific using the "dot" . notation (e.g. line item options for orders, or price tiers for SKUs).
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 exported).
Supported associations
Only specific includes are allowed for each resource:
Bundles — sku_list, sku_list_items
Customer subscriptions — customer
Customers — customer_subscriptions
Orders — customer, shipping_address, billing_address, line_items.line_item_options
Prices — sku and price_tiers
Shipping categories — skus 
SKUs — shipping_category, prices.price_tiers, stock_items, tax_categories
SKU list — sku_list_items, bundles
SKU list items — sku
Stock items — sku
Tax categories — sku
Filtering exported data
When exporting resources, you can fine-tune the data to be exported by applying some filters using the filters attribute:
...
  "filters": {
    "{{predicate}}": {{value}},
    ...
  }
To compose the filter predicate you just need to follow the same syntax 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).
Filtering data
Skipping redundant attributes
You might want to compact exported data by removing some redundant attributes from the final JSON or CSV output. About that, you can use some specific boolean attributes to set some preferences — these are the ones supported at the moment:
skip_ids — to remove from the export output the parent resource IDs.
skip_rel_ids —  to remove from the export output the relationship IDs.
skip_timestamps — to remove from the export output the timestamp attributes (created_at and updated_at).
skip_blanks  —  to remove from the export output any empty or null attribute (available when exporting with the JSON format only).
skip_amount_formats —  to export all the amounts (e.g. for prices, orders, etc.) formatted as cents only.
Examples
Exporting a list of addresses (JSON)
Request
Response
The following request creates an export of a list of addresses in JSON format, skipping the timestamp attributes:
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",
	    "filters": {
	      "country_code_eq": "IT",
	      "city_in": ["Rome", "Milan", "Prato"]
	    },
	    "skip_timestamps": true
	  }
	}
      }'
On success, the API responds with a 201 Created status code, returning the created export object:
{
  "data": {
    "id": "PmjlkIJzRA",
    "type": "exports",
    "links": {...},
    "attributes": {
      "resource_type": "addresses",
      "format": "json",
      "status": "pending",
      "includes": [],
      "filters": {"country_code_eq": "IT", "city_in": ["Rome", "Milan", "Prato"]},
      "skip_ids": null,
      "skip_rel_ids": null,
      "skip_timestamps": true,
      "skip_blanks": null,
      "skip_amount_formats": null,
      "started_at": null,
      "completed_at": null,
      "interrupted_at": null,
      "records_count": 8765,
      "attachment_url": null,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "meta": {...}
  }
}
Exporting a list of bundles with SKU lists and SKU list items (CSV)
Request
Response
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, and skipping the bundle IDs:
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": ["six pack", "12 pack"]
	    },
	    "skip_ids": true
	  }
	}
      }'
On success, the API responds with a 201 Created status code, returning the created export object:
{
  "data": {
    "id": "PmjlkIJzRA",
    "type": "exports",
    "links": {...},
    "attributes": {
      "resource_type": "bundles",
      "format": "csv",
      "status": "in_progress",
      "includes": ["sku_list", "sku_list_items"],
      "filters": {"sku_list_name_in": ["six pack", "12 pack"]},
      "skip_ids": true,
      "skip_rel_ids": null,
      "skip_timestamps": null,
      "skip_blanks": null,
      "skip_amount_formats": null,
      "started_at": null,
      "completed_at": null,
      "interrupted_at": null,
      "records_count": 43,
      "attachment_url": null,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "meta": {...}
  }
}
Exporting a list of coupons (JSON)
Request
Response
The following request creates an export of a list of coupons in JSON format, skipping the timestamps and any empty or null attributes:
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",
	    "skip_timestamps": true,
	    "skip_blanks": true
	  }
	}
      }'
On success, the API responds with a 201 Created status code, returning the created export object:
{
  "data": {
    "id": "PmjlkIJzRA",
    "type": "exports",
    "links": {...},
    "attributes": {
      "resource_type": "coupons",
      "format": "json",
      "status": "in_progress",
      "includes": [],
      "filters": {},
      "skip_ids": null,
      "skip_rel_ids": null,
      "skip_timestamps": true,
      "skip_blanks": true,
      "skip_amount_formats": null,
      "started_at": null,
      "completed_at": null,
      "interrupted_at": null,
      "records_count": 9876,
      "attachment_url": null,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "meta": {...}
  }
}
Exporting a list of customer subscriptions with customers (CSV)
Request
Response
The following request creates an export of a list of customer subscriptions and their associated customers in CSV format, filtered by email:
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"
	    }
	  }
	}
      }'
On success, the API responds with a 201 Created status code, returning the created export object:
{
  "data": {
    "id": "PmjlkIJzRA",
    "type": "exports",
    "links": {...},
    "attributes": {
      "resource_type": "customer_subscriptions",
      "format": "csv",
      "status": "in_progress",
      "includes": ["customer"],
      "filters": {"customer_email_matches": "%gmail.com"},
      "skip_ids": null,
      "skip_rel_ids": null,
      "skip_timestamps": null,
      "skip_blanks": null,
      "skip_amount_formats": null,
      "started_at": null,
      "completed_at": null,
      "interrupted_at": null,
      "records_count": 345,
      "attachment_url": null,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "meta": {...}
  }
}
Exporting a list of customers with customer subscriptions (JSON)
Request
Response
The following request creates an export of a list of customers in JSON format, filtered by email, and skipping the customer and customer subscription IDs, plus any empty or null attributes:
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",
	    "includes": ["customer_subscriptions"],
	    "filters": {
	      "email_end": ".com"
	    },
	    "skip_ids": true,
	    "skip_rel_ids": true,
	    "skip_blanks": true
	  }
	}
      }'
On success, the API responds with a 201 Created status code, returning the created export object:
{
  "data": {
    "id": "PmjlkIJzRA",
    "type": "exports",
    "links": {...},
    "attributes": {
      "resource_type": "customers",
      "format": "json",
      "status": "in_progress",
      "includes": ["customer_subscriptions"],
      "filters": {"email_end": ".com"},
      "skip_ids": true,
      "skip_rel_ids": true,
      "skip_timestamps": null,
      "skip_blanks": true,
      "skip_amount_formats": null,
      "started_at": null,
      "completed_at": null,
      "interrupted_at": null,
      "records_count": 254,
      "attachment_url": null,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "meta": {...}
  }
}
Exporting a list of gift cards (CSV)
Request
Response
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:
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"
	    }
	  }
	}
      }'
On success, the API responds with a 201 Created status code, returning the created export object:
{
  "data": {
    "id": "PmjlkIJzRA",
    "type": "exports",
    "links": {...},
    "attributes": {
      "resource_type": "gift_cards",
      "format": "csv",
      "status": "in_progress",
      "includes": [],
      "filters": {"created_at_gteq": "2018-01-01T12:00:00.000Z"},
      "skip_ids": null,
      "skip_rel_ids": null,
      "skip_timestamps": null,
      "skip_blanks": null,
      "skip_amount_formats": null,
      "started_at": null,
      "completed_at": null,
      "interrupted_at": null,
      "records_count": 349,
      "attachment_url": null,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "meta": {...}
  }
}
Exporting a list of orders with customer addresses, line items, and line item options (JSON)
Request
Response
The following request creates an export of a list of orders with the associated customer, addresses, line items, and line item options in JSON format, filtered by status, country code, and the date and time at which they were placed. The orders (and any included resource) IDs are skipped, along with the timestamps and any empty or null attribute. All the amounts are exported formatted as cents only:
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"
	    ],
	    "filters": {
	      "status_in": ["placed", "approved"],
	      "placed_at_gteq": "2018-01-01T12:00:00.000Z",
	      "country_code_eq": "IT"
	    },
	    "skip_ids": true,
	    "skip_rel_ids": true,
	    "skip_timestamps": true,
	    "skip_blanks": true,
	    "skip_amount_formats": true
	  }
	}
      }'
On success, the API responds with a 201 Created status code, returning the created export object:
{
  "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"],
      "filters": {"status_in": ["placed", "approved"], "placed_at_gteq": "2018-01-01T12:00:00.000Z", "country_code_eq": "IT"},
      "skip_ids": true,
      "skip_rel_ids": true,
      "skip_timestamps": true,
      "skip_blanks": true,
      "skip_amount_formats": true,
      "started_at": null,
      "completed_at": null,
      "interrupted_at": null,
      "records_count": 6499,
      "attachment_url": null,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "meta": {...}
  }
}
Exporting a list of prices with price tiers (CSV)
Request
Response
The following request creates an export of a list of prices with associated price tiers in CSV format, filtered by the associated price list's currency code. The price tier IDs are skipped, and all the amounts are exported as cents only:
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",
	    "includes": ["price_tiers"],
	    "filters": {
	      "price_list_currency_code_eq": "USD"
	    },
	    "skip_rel_ids": true,
	    "skip_amount_formats": true
	  }
	}
      }'
On success, the API responds with a 201 Created status code, returning the created export object:
{
  "data": {
    "id": "PmjlkIJzRA",
    "type": "exports",
    "links": {...},
    "attributes": {
      "resource_type": "prices",
      "format": "csv",
      "status": "in_progress",
      "includes": ["price_tiers"],
      "filters": {"price_list_currency_code_eq": "USD"},
      "skip_ids": null,
      "skip_rel_ids": true,
      "skip_timestamps": null,
      "skip_blanks": null,
      "skip_amount_formats": true,
      "started_at": null,
      "completed_at": null,
      "interrupted_at": null,
      "records_count": 3456,
      "attachment_url": null,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "meta": {...}
  }
}
Exporting a list of SKU lists with SKU list items (JSON)
Request
Response
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), and skipping any empty or null attributes:
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
	    },
	    "skip_blanks": true
	  }
	}
      }'
On success, the API responds with a 201 Created status code, returning the created export object:
{
  "data": {
    "id": "PmjlkIJzRA",
    "type": "exports",
    "links": {...},
    "attributes": {
      "resource_type": "sku_lists",
      "format": "json",
      "status": "in_progress",
      "includes": ["sku_list_items"],
      "filters": {"manual_true": true},
      "skip_ids": null,
      "skip_rel_ids": true,
      "skip_timestamps": null,
      "skip_blanks": true,
      "skip_amount_formats": null,
      "started_at": null,
      "completed_at": null,
      "interrupted_at": null,
      "records_count": 3456,
      "attachment_url": null,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "meta": {...}
  }
}
Exporting a list of SKUs with prices, price tiers, stock items, and tax categories (JSON)
Request
Response
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, filtered by SKU name, and skipping any empty or null attribute. All the amounts are exported as cents only:
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"
	    },
	    "skip_blanks": true,
	    "skip_amount_formats": true
	  }
	}
      }'
On success, the API responds with a 201 Created status code, returning the created export object:
{
  "data": {
    "id": "PmjlkIJzRA",
    "type": "exports",
    "links": {...},
    "attributes": {
      "resource_type": "skus",
      "format": "json",
      "status": "in_progress",
      "includes": ["prices.price_tiers", "stock_items", "tax_categories"],
      "filters": {"name_cont": "FW"},
      "skip_ids": null,
      "skip_rel_ids": null,
      "skip_timestamps": null,
      "skip_blanks": true,
      "skip_amount_formats": true,
      "started_at": null,
      "completed_at": null,
      "interrupted_at": null,
      "records_count": 2345,
      "attachment_url": null,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "meta": {...}
  }
}
Exporting a list of stock items with SKUs (CSV)
Request
Response
The following request creates an export of a list of stock items and the associated SKUs in CSV format, filtered by stock item quantity, and skipping both the stock item and the SKU IDs:
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",
	    "includes": ["sku"],
	    "filters": {
	      "quantity_gteq": 1
	    },
	    "skip_ids": true,
	    "skip_rel_ids": true
	  }
	}
      }'
On success, the API responds with a 201 Created status code, returning the created export object:
{
  "data": {
    "id": "PmjlkIJzRA",
    "type": "exports",
    "links": {...},
    "attributes": {
      "resource_type": "stock_items",
      "format": "csv",
      "status": "in_progress",
      "includes": ["sku"],
      "filters": {"quantity_gteq": 1},
      "skip_ids": true,
      "skip_rel_ids": true,
      "skip_timestamps": null,
      "skip_blanks": true,
      "skip_amount_formats": null,
      "started_at": null,
      "completed_at": null,
      "interrupted_at": null,
      "records_count": 4567,
      "attachment_url": null,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "meta": {...}
  }
}
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.
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.
Request
Response
curl -g -X GET \ 
  'https://yourdomain.commercelayer.io/api/exports/PmjlkIJzRA' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'
On success, the API responds with a 200 OK status code, returning the single export object:
{
  "data": {
    "id": "PmjlkIJzRA",
    "type": "exports",
    "links": {...},
    "attributes": {
      "resource_type": "stock_items",
      "format": "csv",
      "status": "completed",
      "includes": ["sku"],
      "filters": {"quantity_gteq": 1},
      "skip_ids": true,
      "skip_rel_ids": true,
      "skip_timestamps": null,
      "skip_blanks": true,
      "skip_amount_formats": null,
      "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/",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "meta": {...}
  }
}
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.
Real-time webhooks
Importing resources
External resources
Last modified 9d ago
Copy link
On this page
Attachment URL
Export limits
Supported resources
Including associations
Filtering exported data
Skipping redundant attributes
Examples
Checking the export status