Introducing our brand new Rules Engine —
Read the docs
LogoLogo
Core APIOther APIsChangelog
Getting started
Getting started
  • Welcome to Commerce Layer
    • Guided setup
    • Manual configuration
  • API specification
  • API credentials
  • Authentication
    • Client credentials
    • Password
    • Authorization code
    • Refresh token
    • JWT bearer
    • Revoking a token
  • Roles and permissions
  • Fetching resources
  • Fetching relationships
  • Including associations
  • Sparse fieldsets
  • Sorting results
  • Pagination
  • Filtering data
  • Creating resources
  • Updating resources
  • Tagging resources
  • Deleting resources
  • Importing resources
  • Exporting resources
  • Cleaning up resources
  • External resources
    • External order validation
    • External prices
    • External shipping costs
    • External payment gateways
    • External promotions
    • External tax calculators
  • Rate limits
  • Handling errors
  • Real-time webhooks
  • Callbacks security
On this page
  • Attachment URL
  • Export limits
  • Supported resources
  • Including associations
  • Selecting fields
  • Filtering exported data
  • Skipping redundant attributes
  • Examples
  • Checking the export status
  • Webhooks for exports

Exporting resources

How to bulk export resources and their relationships

PreviousImporting resourcesNextCleaning up resources

Last updated 5 months ago

Commerce Layer lets you export resources in JSON (default) or CSV formats. To do that, you need to create a new , 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 , apply some to narrow the exported data, and decide to some redundant attributes.

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).

The process is asynchronous and you can poll the status attribute to . 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 .

Attachment URL

Once the export process is completed, the results are compressed () and uploaded to an external storage service (currently ). 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 to get a new working one.

Export limits

Maximum export size

There is no limit on the total number of resources you can export, but the single batches 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.

If you absolutely need to export any of the in one go, overriding the API limits above, you can leverage the power of our (). Alternatively, you can also perform a using our (at the moment limited to , , and ).

Supported resources

At the moment, exports are available for almost all of the resources . Please find some examples of how to export them .

Including associations

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.

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).

Supported associations

In case you specify an invalid include for the exported resource, an error is raised before creating (and starting) the export.

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.

If you want to export all the fields of a resource, use the asterisk * (works both for the main and related resources).

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:

...
  "fields": [
    "code",
    "name",
    "prices.amount_cents",
    "prices.price_list.name",
    "stock_items.stock_location.code",
    "shipping_category.*"
    ...
  ]

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.

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.

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.

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:

...
  "filters": {
    "{{predicate}}": {{value}},
    ...
  }

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.).

Examples

Exporting some fields of a filtered list of addresses (JSON)

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:

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" ]
	    }
	  }
	}
      }'

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": [],
      "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": {...}
  }
}

Exporting a filtered list of bundles with SKU lists and SKU list items (CSV)

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:

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" ]
	    }
	  }
	}
      }'

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"],
      "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": {...}
  }
}

Exporting a list of coupons (JSON)

The following request creates an export of a list of coupons in JSON format, skipping the redundant 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",
	    "dry_data": 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": [],
      "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": {...}
  }
}

Exporting some fields a filtered list of customer addresses with addresses and customers (JSON)

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:

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"
	    }
	  }
	}
      }'

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_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": {...}
  }
}

Exporting a filtered list of customer subscriptions with customers (CSV)

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"],
      "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": {...}
  }
}

Exporting some fields of a filtered list of customers with customer subscriptions (JSON)

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:

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"
	    }
	  }
	}
      }'

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"],
      "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": {...}
  }
}

Exporting a filtered list of gift cards (CSV)

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": [],
      "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": {...}
  }
}

Exporting a filtered list of orders with customer, addresses, line items, line item options, payment method, and refunds (JSON)

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:

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
	  }
	}
      }'

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", "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": {...}
  }
}

Exporting a filtered list of order subscriptions with order subscription items and customer payment source (JSON)

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:

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
	  }
	}
      }'

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": "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": {...}
  }
}

Exporting some fields of a filtered list of prices with price tiers (CSV)

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:

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
	  }
	}
      }'

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": ["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": {...}
  }
}

Exporting a filtered list of SKU lists with SKU list items (JSON)

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):

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
	    }
	  }
	}
      }'

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"],
      "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": {...}
  }
}

Exporting a filtered list of SKUs with prices, price tiers, stock items, and tax categories (JSON)

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
	  }
	}
      }'

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" ],
      "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": {...}
  }
}

Exporting some fields of a filtered list of stock items with SKUs and stock location (CSV)

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:

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
	  }
	}
      }'

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", "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": {...}
  }
}

Exporting some fields of a filtered list of stock transfers with SKUs and stock locations (CSV)

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:

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
	  }
	}
      }'

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_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": {...}
  }
}

Exporting all the tags (CSV)

The following request creates an export of all the tags you created for your organization in CSV format:

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"
          }
        }
      }'

On success, the API responds with a 201 Created status code, returning the created export object:

{
  "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": { ... }
  }
}

Exporting some fields of all the SKUs tagged with at least one of two tags (JSON)

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:

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" ]
            }
          }
        }
      }'

On success, the API responds with a 201 Created status code, returning the created export object:

{
  "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": { ... }
  }
}

When filtering a list of tagged resources by tag(s) the only allowed predicates are tags_id_in and tags_id_not_in.

Exporting more than 10K orders using the CLI

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

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

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.

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"],
      "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": {...}
  }
}

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.

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.

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.

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 . If you're using the export + import features to duplicate your dataset records (e.g. to migrate your test data to your live ) you may need to 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 when exporting the data you plan to re-import elsewhere (use instead).

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 for more information on how resources relate to each other.

When including associations, multiple levels of relationships are supported. You just need to append the more specific using the use the . (e.g. , or ).

All of the valid resource relationships can be included when exporting. Please refer to the specific resource page in the to check which relationships you can include when exporting it.

For the main exported resource you can pass fields using the plain attribute names. For any related association's attribute use the (the same used when ), i.e. . followed by the field name.

To compose the filter predicate you just need to follow the 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 ).

Importing resources
data model
Filtering data
Real-time webhooks
dot notation
line item options for orders
price tiers for SKUs
dot notation
including associations
same syntax
this example
Core API reference
gzip
Amazon S3
CLI export plugin
include
filters
skip
check the export progress
included associations
fetch the completed export
supported resources
see example
here below
Metrics API
exposed via API
imports API
skip
fields
includes
environment
search query
export resource
orders
carts
returns