Importing resources
How to bulk import resources and their relationships
Commerce Layer lets you import multiple resources in batches. To do that, you need to create a new import resource, specify the
resource_type
you want to import, and populate the inputs
attribute with a JSON (default) or CSV list of items. Each element of the inputs
list (which is an array of objects for JSON and a string for CSV) contains the resource attributes and relationships.To import a CSV list you need to set the
format
attribute to csv
. Otherwise, if the format is not specified, the import API will assume you're using the default format (JSON) and return an error.When importing a CSV list of items you also need to flatten the resource attributes and relationships on a single line. The headers for the attributes of a relationship must be prepended by the associated resource name (see example). When importing tags together with a tagged resource the elements related to the
tags.id
and tags.name
headers can contain a string with the list of IDs/names, comma separated (see example). In general, using CSV is fine for simple imports (resources with a few attributes and no relationship included), otherwise we strongly recommend using JSON to ensure better readability in terms of inputs
list.The process is asynchronous and you can poll the
status
attribute to check the import progress. Once the import has been completed you can check the number of imported items by inspecting the processed_count
attribute. In case of validation errors, the errors_count
and errors_log
attributes are populated.Resource relationships can be addressed by using their IDs. To do that, you need to append the
_id
suffix to the name of the related resource (e.g. price_list_id
). Some relationships can also be specified as a nested array of objects (e.g. order line items, price tiers, SKU list items, etc.).When an import is started, the data you pass within the
inputs
list is validated, compressed (gzip), and then uploaded to an external storage service (currently Amazon S3). You can download the imported data using the link exposed in the attachment_url
attribute, which is populated as soon as the import is completed.External storage service URLs expire in 5 minutes. You need to uncompress (
gunzip
) the file in order to read the data back. If the imported data URL is expired you can just fetch the completed import to get a new working one.There is no limit on the total number of resources you can import, but the single batches are subject to some soft limits: the
inputs
array must contain a maximum of 10000 items, otherwise the import will be rejected at the time of creation.During the import process, the errors count is also monitored: imports whose
errors_count
attribute value overflows the maximum percentage of 10% of the total import size (i.e. the number of items contained in the inputs
array) will be interrupted.The maximum number of concurrent imports (i.e. imports whose status is
pending
or in_progess
) allowed per organization is 10.If you absolutely need to import any of the supported resources in one go, overriding the maximum import size and concurrent imports API limits above, you can leverage the power of our CLI import plugin (see example).
At moment, imports are available for the following resources (more to come):
- Addresses
- Bundles
- Coupons
- Customer addresses
- Customer payment sources
- Customer subscriptions
- Customers
- Gift cards
- Line items
- Line item options
- Orders
- Price tiers
- Prices
- Shipping categories
- SKU list items
- SKU lists
- SKU options
- SKUs
- Stock items
- Tags
- Tax categories
With very few exceptions (e.g. shipments, transactions, etc.) you can use as
inputs
any output (both in JSON or CSV format) you get from the exports API.If the single resource to be imported doesn't exist it gets created, otherwise it is updated.
In order to detect if a resource already exists the
id
key is checked for each inputs
array element. Some resources also support specific (combined) attributes to identify an existing record, which can be helpful in case the resource ID isn't known during the import process:- Bundles —
code
+market_id
- Coupons —
code
+promotion_rule_id
- Customer addresses —
customer_id
- Customer subscriptions —
customer_id
+reference
- Customers —
email
- Gift cards —
code
- Orders —
number
- Prices —
sku_code
+price_list_id
- Shipping categories —
name
- SKU options —
name
+market_id
- SKUs —
code
- Stock items —
sku_code
+stock_location_id
- Tags —
name
- Tax categories —
code
+tax_calculator_id
In case both the specific unique key and the
id
are passed, the latter is used to identify existing records to be updated. This way is possible to modify the value of the specific unique key with a new one (i.e. changing the code
of an SKU or the number
of an order). Keep in mind that in this case every entry of the inputs
array must have the id
key, otherwise the specific key is used to identify the record and the import result could not be as expected (e.g. new records could be created instead of updating existing ones).If the resources you're importing refer to the same parent resource (e.g. prices to the same price list), you can avoid repeating its value on each inputs items by specifying the
parent_resource_id
attribute. In case you specify both the parent resource ID and the relationship ID for each item, the latter wins. These are the supported parent resources:- Bundles —
market_id
- Coupons —
promotion_rule_id
- Customer payment sources —
payment_method_id
- Gift cards —
market_id
- Orders —
market_id
- Prices —
price_list_id
- SKU list items —
sku_list_id
- SKU options —
market_id
- Stock items —
stock_location_id
- Tax categories —
tax_calculator_id
Request
Response
The following request creates an import with a list of addresses in CSV format:
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/imports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "imports",
"attributes": {
"resource_type": "addresses",
"format": "csv",
"inputs": "first_name,last_name,company,line_1,city,zip_code,state_code,country_code,phone,email\nGeorge,Harrison,The Beatles,Viale Borgo Valsugana 93,Prato,59100,PO,IT,+39 0574 933550, [email protected]\n"
}
}
}'
On success, the API responds with a
201 Created
status code, returning the created import object:{
"data": {
"id": "PmjlkIJzRA",
"type": "imports",
"links": { ... },
"attributes": {
"resource_type": "addresses",
"format": "csv",
"parent_resource_id": null,
"status": "pending",
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"inputs": "...",
"inputs_size": 100,
"errors_count": 0,
"warnings_count": 0,
"destroyed_count": 0,
"processed_count": 0,
"cleanup_records": false,
"attachment_url": nil,
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": { ... }
}
}
For a list of all the required attributes you need to create an address, refer to the related section of the API reference.
Request
Response
The following request creates an import with a list of bundles in JSON format:
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/imports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "imports",
"attributes": {
"resource_type": "bundles",
"parent_resource_id": "bgOEQhznoZ",
"inputs": [
{
"code":"FWOUTFIT",
"name":"FW outfit",
"image_url":"https://img.yourdomain.com/bundles/FWOUTFIT.png",
"reference": "FWOUTFIT",
"sku_list_id": "GHYfrWszHp"
},
{
"code":"SSOUTFIT",
"name":"SS outfit",
"image_url":"https://img.yourdomain.com/bundles/SSOUTFIT.png",
"reference": "SSOUTFIT",
"sku_list_id": "GHYfrWszHp"
},
{ ... }
]
}
}
}'
On success, the API responds with a
201 Created
status code, returning the created import object:{
"data": {
"id": "PmjlkIJzRA",
"type": "imports",
"links": { ... },
"attributes": {
"resource_type": "bundles",
"format": "json",
"parent_resource_id": "bgOEQhznoZ",
"status": "pending",
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"inputs": [ ... ],
"inputs_size": 100,
"errors_count": 0,
"warnings_count": 0,
"destroyed_count": 0,
"processed_count": 0,
"cleanup_records": false,
"attachment_url": nil,
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": { ... }
}
}
For a list of all the required attributes you need to create a bundle, refer to the related section of the API reference.
Request
Response
The following request creates an import with a list of coupons in CSV format and clean-up the ones existing for the same promotion rule:
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/imports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "imports",
"attributes": {
"resource_type": "coupons",
"format": "csv",
"parent_resource_id": "FreQKlNxZA",
"inputs": "code,customer_single_use,usage_limit,usage_count,recipient_email\n11111111,false,,0,\n22222222,false,,0,\n33333333,false,,0,[email protected]\n"
]
}
}
}'
On success, the API responds with a
201 Created
status code, returning the created import object:{
"data": {
"id": "PmjlkIJzRA",
"type": "imports",
"links": { ... },
"attributes": {
"resource_type": "coupons",
"format": "csv",
"parent_resource_id": "FreQKlNxZA",
"status": "pending",
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"inputs": "...",
"inputs_size": 3,
"errors_count": 0,
"warnings_count": 0,
"destroyed_count": 0,
"processed_count": 0,
"cleanup_records": false,
"attachment_url": nil,
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": { ... }
}
}
For a list of all the required attributes you need to create a coupon, refer to the related section of the API reference.
Request
Response
The following request creates an import with a list of customer addresses in JSON format (the associated address can be either specified by ID if existing or created if not existing):
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/imports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "imports",
"attributes": {
"resource_type": "customer_addresses",
"inputs": [
{
"customer_email": "[email protected]",
"address_id": "gHbVCxZSdE"
},
{
"customer_email": "[email protected]",
"address": {
"first_name": "Paul",
"last_name": "Mc Cartney",
"line_1": "Viale Borgo Valsugana 93",
"city": "Prato",
"zip_code": "59100",
"state_code": "PO",
"country_code": "IT",
"phone": "+39 0574 933550"
}
},
{ ... }
]
}
}
}'
On success, the API responds with a
201 Created
status code, returning the created import object:{
"data": {
"id": "NqYzgIKvdm",
"type": "imports",
"links": { ... },
"attributes": {
"resource_type": "customer_addresses",
"format": "json",
"parent_resource_id": null,
"status": "pending",
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"inputs": [ ... ],
"inputs_size": 100,
"errors_count": 0,
"warnings_count": 0,
"destroyed_count": 0,
"processed_count": 0,
"errors_log": {},
"warnings_log": {},
"cleanup_records": false,
"attachment_url": nil,
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": { ... }
}
}
Request
Response
The following request creates an import with a list of customer payment sources in JSON format (you must always provide the
customer_token
and payment_source_token
you've got from your payment gateway):curl -g -X POST \
'https://yourdomain.commercelayer.io/api/imports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "imports",
"attributes": {
"resource_type": "customer_payment_sources",
"parent_resource_id": "hgTfDcXXzs",
"inputs": [
{
"customer_token": "255203791",
"payment_source_token: "5f8k2cr",
"customer_id": "hGdEwsAqlK"
},
{
"customer_token": "255265209",
"payment_source_token: "6gh02cz",
"customer_id": "jHgfTTrcVn"
},
{ ... }
]
}
}
}'
On success, the API responds with a
201 Created
status code, returning the created import object:{
"data": {
"id": "NqYzgIKvdm",
"type": "imports",
"links": { ... },
"attributes": {
"resource_type": "customer_payment_sources",
"format": "json",
"parent_resource_id": "hgTfDcXXzs",
"status": "pending",
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"inputs": [ ... ],
"inputs_size": 100,
"errors_count": 0,
"warnings_count": 0,
"destroyed_count": 0,
"processed_count": 0,
"errors_log": {},
"warnings_log": {},
"cleanup_records": false,
"attachment_url": nil,
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": { ... }
}
}
To create an import of customer payment sources you must always provide the
customer_token
and payment_source_token
you got from your payment gateway.For a list of all the required attributes you need to create a customer payment sources, refer to the related section of the API reference.
Request
Response
The following request creates an import with a list of customer subscriptions in JSON format:
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/imports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "imports",
"attributes": {
"resource_type": "customer_subscriptions",
"inputs": [
{
"customer_email": "[email protected]",
"reference": "Marketing newsletter"
},
{
"customer_email": "[email protected]",
"reference": "Whitepaper download"
},
{ ... }
]
}
}
}'
On success, the API responds with a
201 Created
status code, returning the created import object:{
"data": {
"id": "NqYzgIKvdm",
"type": "imports",
"links": { ... },
"attributes": {
"resource_type": "customer_subscriptions",
"format": "json",
"parent_resource_id": null,
"status": "pending",
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"inputs": [ ... ],
"inputs_size": 100,
"errors_count": 0,
"warnings_count": 0,
"destroyed_count": 0,
"processed_count": 0,
"errors_log": {},
"warnings_log": {},
"cleanup_records": false,
"attachment_url": nil,
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": { ... }
}
}
For a list of all the required attributes you need to create a customer subscription, refer to the related section of the API reference.
Request
Response
The following request creates an import with a list of customers in CSV format:
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/imports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "imports",
"attributes": {
"resource_type": "customers",
"format": "csv",
"inputs": "email,password,customer_group_id\[email protected],,\[email protected],secret,KngqdhAlpd\n"
}
}
}'
On success, the API responds with a
201 Created
status code, returning the created import object:{
"data": {
"id": "ZqDQzIoznm",
"type": "imports",
"links": { ... },
"attributes": {
"resource_type": "customers",
"format": "csv",
"parent_resource_id": null,
"status": "pending",
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"inputs": "...",
"inputs_size": 100,
"errors_count": 0,
"warnings_count": 0,
"destroyed_count": 0,
"processed_count": 0,
"errors_log": {},
"warnings_log": {},
"cleanup_records": false,
"attachment_url": nil,
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": { ... }
}
}
For a list of all the required attributes you need to create a customer, refer to the related section of the API reference.
Request
Response
The following request creates an import with a list of gift cards in JSON format:
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/imports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "imports",
"attributes": {
"resource_type": "gift_cards",
"parent_resource_id": "bgOEQhznoZ",
"inputs": [
{
"balance_cents": 12500,
"currency_code": "USD",
"single_use": false,
"rechargeable": true,
"image_url": "https://img.yourdomain.com/skus/MYGITFCARDIMAGE.png",
"expires_at": "2030-01-01T00:00:00Z",
"recipient_email": "[email protected]"
},
{
"balance_cents": 20000,
"currency_code": "EUR",
"single_use": true,
"rechargeable": false,
"expires_at": "2025-01-01T00:00:00Z",
"recipient_email": "[email protected]"
},
{ ... }
]
}
}
}'
On success, the API responds with a
201 Created
status code, returning the created import object:{
"data": {
"id": "BAzkwIRNkq",
"type": "imports",
"links": { ... },
"attributes": {
"resource_type": "gift_cards",
"format": "json",
"parent_resource_id": "bgOEQhznoZ",
"status": "pending",
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"inputs": [ ... ],
"inputs_size": 100,
"errors_count": 0,
"warnings_count": 0,
"destroyed_count": 0,
"processed_count": 0,
"errors_log": {},
"warnings_log": {},
"cleanup_records": false,
"attachment_url": nil,
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": { ... }
}
}
To create an import of gift cards for the same market, remember to specify its ID as the
parent_resource_id
attribute. On the other hand, specifying the market_id
or the market_code
attributes for every single item of the inputs
list lets you import gift cards associated with different markets all at once.For a list of all the required attributes you need to create a gift card, refer to the related section of the API reference.
Request
Response
The following request creates an import with a list of orders with associated line items and line item options in JSON format:
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/imports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "orders",
"attributes": {
"resource_type": "orders",
"parent_resource_id": "KmjljGJzWQ"
"inputs": [
{
"customer_email": "[email protected]",
"line_items": [
{
"item_type": "sku",
"name": "BABYONBU000000E63E7424MX",
"quantity": 2,
"unit_amount_cents": 1000,
"line_item_options": [
{
"name": "engraving",
"sku_option_id": "GhFDsAWqRU",
"quantity": 1
},
{
"name": "embossing",
"sku_option_id": "hJgFCvBNmK",
"quantity": 2
}
]
},
{
"item_type": "sku",
"name": "BABYONBU000000E63E7418MX",
"quantity": 1,
"unit_amount_cents": 2000
}
]
},
{
"customer_email": "[email protected]",
"_archive": 1,
"line_items": [
{
"item_type": "sku",
"name": "BABYONBU000000E63E7667MX",
"quantity": 2,
"unit_amount_cents": 1500
}
]
},
{ ... }
]
}
}
}'
On success, the API responds with a
201 Created
status code, returning the created import object:{
"data": {
"id": "PmjlkIJzRA",
"type": "imports",
"links": { ... },
"attributes": {
"resource_type": "orders",
"format": "json",
"parent_resource_id": "KmjljGJzWQ",
"status": "pending",
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"inputs": [ ... ],
"inputs_size": 100,
"errors_count": 0,
"warnings_count": 0,
"destroyed_count": 0,
"processed_count": 0,
"errors_log": {},
"warnings_log": {},
"cleanup_records": false,
"attachment_url": nil,
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": { ... }
}
To create an import of orders for the same market, remember to specify its ID as the
parent_resource_id
attribute. On the other hand, specifying the market_id
or the market_code
attributes for every single item of the inputs
list lets you import orders associated with different markets all at once.For a list of all the required attributes you need to create an order, refer to the related section of the API reference.
Request
Response
The following request creates an import with a list of prices and the associated price tiers in CSV format:
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/imports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "imports",
"attributes": {
"resource_type": "prices",
"format": "csv",
"parent_resource_id": "vLrWRCJWBE",
"inputs": "currency_code,sku_code,amount_cents,compare_at_amount_cents,price_tiers.type,price_tiers.name,price_tiers.up_to,price_tiers.price_amount_cents\nEUR,REDHANDBAG,1000,1000,PriceVolumeTier,10 pack,10,600\nEUR,REDHANDBAG,1000,1000,PriceVolumeTier,20 pack,20,400\nEUR,BLUEHANDBAG,2000,2000,PriceVolumeTier,XL pack,,300\n"
}
}
}'
On success, the API responds with a
201 Created
status code, returning the created import object:{
"data": {
"id": "ZbDQzIoxnA",
"type": "imports",
"links": { ... },
"attributes": {
"resource_type": "prices",
"format": "csv",
"parent_resource_id": "vLrWRCJWBE",
"status": "pending",
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"inputs": "...",
"inputs_size": 45,
"errors_count": 0,
"warnings_count": 0,
"destroyed_count": 0,
"processed_count": 0,
"cleanup_records": false,
"attachment_url": nil,
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": { ... }
}
}
To create an import of prices for the same price list, remember to specify its ID as the
parent_resource_id
attribute. On the other hand, specifying the price_list_id
or the price_list_code
attributes for every single item of the inputs
list lets you import prices associated with different price lists all at once.For a list of all the required attributes you need to create a price, refer to the related section of the API reference. More info about price volume tiers here.
Request
Response
The following request creates an import with a list of SKU lists with associated SKU list items in JSON format:
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/imports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "imports",
"attributes": {
"resource_type": "sku_lists",
"inputs": [
{
"name":"Promotional Items 15%",
"sku_list_items": [
{
"sku_code": "BABYONBU000000E63E7667MX",
},
{
"sku_code": "BABYONBU000000E63E7418MX",
}
]
},
{ ... }
]
}
}
}'
On success, the API responds with a
201 Created
status code, returning the created import object:{
"data": {
"id": "PmjlkIJzRA",
"type": "imports",
"links": { ... },
"attributes": {
"resource_type": "sku_lists",
"format": "json",
"parent_resource_id": null,
"status": "pending",
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"inputs": [ ... ],
"inputs_size": 100,
"errors_count": 0,
"warnings_count": 0,
"destroyed_count": 0,
"processed_count": 0,
"cleanup_records": false,
"attachment_url": nil,
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": { ... }
}
For a list of all the required attributes you need to create an SKU list, refer to the related section of the API reference.
Request
Response
The following request creates an import with a list of SKU options in CSV format:
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/imports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "imports",
"attributes": {
"resource_type": "sku_options",
"format": "csv",
"parent_resource_id": "XHnLEsQaZp",
"inputs": "name,price_amount_cents,sku_code_regex\n,engraving,500,^A\nshipping costs,700,^B\n"
}
}
}'
On success, the API responds with a
201 Created
status code, returning the created import object:{
"data": {
"id": "PmjlkIJzRA",
"type": "imports",
"links": { ... },
"attributes": {
"resource_type": "sku_options",
"format": "csv",
"parent_resource_id": "XHnLEsQaZp",
"status": "pending",
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"inputs": "...",
"inputs_size": 2,
"errors_count": 0,
"warnings_count": 0,
"destroyed_count": 0,
"processed_count": 0,
"cleanup_records": false,
"attachment_url": nil,
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": { ... }
}
For a list of all the required attributes you need to create an SKU option, refer to the related section of the API reference.
Request
Response
The following request creates an import with a list of SKUs in JSON format:
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/imports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "imports",
"attributes": {
"resource_type": "skus",
"inputs": [
{
"code":"BABYONBU000000E63E7424MX",
"name":"Black Baby Onesie Short Sleeve with Pink Logo (24 Months)",
"image_url":"https://img.yourdomain.com/skus/BABYONBU000000E63E74.png",
"reference": "BABYONBU000000E63E74",
"shipping_category_code": "2_days"
},
{
"code":"BABYONBU000000E63E7418MX",
"name":"Black Baby Onesie Short Sleeve with Pink Logo (18 Months)",
"image_url":"https://img.yourdomain.com/skus/BABYONBU000000E63E74.png",
"reference": "BABYONBU000000E63E74",
"shipping_category_id": "zwzQeFBrNj"
},
{ ... }
]
}
}
}'
On success, the API responds with a
201 Created
status code, returning the created import object:{
"data": {
"id": "PmjlkIJzRA",
"type": "imports",
"links": { ... },
"attributes": {
"resource_type": "skus",
"format": "json",
"parent_resource_id": null,
"status": "pending",
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"inputs": [ ... ],
"inputs_size": 100,
"errors_count": 0,
"warnings_count": 0,
"destroyed_count": 0,
"processed_count": 0,
"cleanup_records": false,
"attachment_url": nil,
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": { ... }
}
}
SKUs have no parent resource, hence the shipping category cannot be used as the
parent_resource_id
attribute. On the other hand, specifying the shipping_category_id
or the shipping_category_code
attributes for every single item of the inputs
list lets you import SKUs associated with different shipping categories all at once (SKUs marked as do_not_ship
included, for which you just can avoid setting any shipping_category_id
at all).For a list of all the required attributes you need to create an SKU, refer to the related section of the API reference.
Request
Response
The following request creates an import with a list of stock items in CSV format:
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/imports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "imports",
"attributes": {
"resource_type": "stock_items",
"format": "csv",
"parent_resource_id": "bnEeQuqZgn",
"inputs": "sku_code,quantity\nBABYONBU000000E63E7424MX,110\nBABYONBU000000E63E7418MX,140\n"
}
}
}'
On success, the API responds with a
201 Created
status code, returning the created import object:{
"data": {
"id": "YqQJGIYWjm",
"type": "imports",
"links": { ... },
"attributes": {
"resource_type": "stock_items",
"format": "json",
"parent_resource_id": "bnEeQuqZgn",
"status": "pending",
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"inputs": "...",
"inputs_size": 2,
"errors_count": 0,
"warnings_count": 0,
"destroyed_count": 0,
"processed_count": 0,
"cleanup_records": false,
"attachment_url": nil,
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": { ... }
}
}
To create an import of stock items for the same stock location, remember to specify the stock location ID as the
parent_resource_id
attribute. On the other hand, specifying the stock_location_id
or the stock_location_code
attributes for every single item of the inputs
list lets you import stock items associated with different stock locations all at once.For a list of all the required attributes you need to create a stock item, refer to the related section of the API reference.
Request
Response
The following request creates an import with a list of tags in CSV format:
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/imports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "imports",
"attributes": {
"resource_type": "tags",
"format": "csv",
"inputs": "name\nbags\nhats\naccessories"
}
}
}'
On success, the API responds with a
201 Created
status code, returning the created import object:{
"data": {
"id": "amJNpILdxm",
"type": "imports",
"links": { ... },
"attributes": {
"resource_type": "tags",
"format": "csv",
"parent_resource_id": null,
"status": "pending",
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"inputs": "...",
"inputs_size": 3,
"errors_count": 0,
"warnings_count": 0,
"destroyed_count": 0,
"processed_count": 0,
"errors_log": {},
"warnings_log": {},
"cleanup_records": null,
"attachment_url": nil,
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"relationships": { ... },
"meta": { ... }
}
For a list of all the required attributes you need to create a tag, refer to the related section of the API reference.
Request
Response
The following request creates an import with a list of SKUs and the associated tags in JSON format:
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/imports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "imports",
"attributes": {
"resource_type": "skus",
"parent_resource_id": "BNdxyFenNG",
"inputs": [
{
"code": "TSHIRTMS000000FFFFFFLXXX",
"name": "Black Men T-Shirt with White Logo (L)",
"tags": [
{
"name": "t_shirts"
}
]
},
{
"code": "TOYCARMINICOUNTRYMANYB",
"name": "Toy Car — Mini Countryman, Yellow/Black",
"tags": [
{
"name": "toys"
},
{
"name": "black_friday"
}
]
},
{
"code": "BASEBCAPLABLUE",
"name": "Baseball Cap LA, Blue",
"tags": [
{
"name": "black_friday"
},
{
"name": "hats"
},
{
"name": "new_collection"
}
]
}
]
}
}
}'
On success, the API responds with a
201 Created
status code, returning the created import object:{
"data": {
"id": "OqPnLIpDxb",
"type": "imports",
"links": { ... },
"attributes": {
"resource_type": "skus",
"format": "json",
"parent_resource_id": "BNdxyFenNG",
"status": "pending",
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"inputs": [ ... ],
"inputs_size": 3,
"errors_count": 0,
"warnings_count": 0,
"destroyed_count": 0,
"processed_count": 0,
"errors_log": {},
"warnings_log": {},
"cleanup_records": null,
"attachment_url": "https://download_link.amazonaws.com/imports_...",
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"relationships": { ... },
"meta": { ... }
}
}
For a list of all the required attributes you need to create a SKU, refer to the related section of the API reference. More info about tags here.
Request
Response
The following request creates an import with a list of customers and the associated tags in CSV format:
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/imports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "imports",
"attributes": {
"resource_type": "customers",
"format": "csv",
"inputs": "email,tags.id,tags.name\[email protected],\"\",\"newsletter\"\[email protected],\"\",\"vip,black_friday\""
}
}
}'
On success, the API responds with a
201 Created
status code, returning the created import object:{
{
"data": {
"id": "BAzkwIeoZq",
"type": "imports",
"links": { ... },
"attributes": {
"resource_type": "customers",
"parent_resource_id": null,
"status": "pending",
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"inputs": [ ... ],
"inputs_size": 2,
"errors_count": 0,
"warnings_count": 0,
"destroyed_count": 0,
"processed_count": 0,
"errors_log": {},
"warnings_log": {},
"cleanup_records": null,
"attachment_url": nil,
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"relationships": { ... },
"meta": { ... }
}
}
}
For a list of all the required attributes you need to create a customer, refer to the related section of the API reference. More info about tags here.
Request
Response
The following request creates an import with a list of tax categories in CSV format:
curl -g -X POST \
'https://yourdomain.commercelayer.io/api/imports' \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer your-access-token' \
-H 'Content-Type: application/vnd.api+json' \
-d '{
"data": {
"type": "imports",
"attributes": {
"resource_type": "tax_categories",
"format": "csv",
"parent_resource_id": "daSWQhzjkiZ",
"inputs": "sku_code,code\nBABYONBU000000E63E7424MX,31000\nBABYONBU000000E63E7418MX,31000\n"
}
}
}'
On success, the API responds with a
201 Created
status code, returning the created import object:{
"data": {
"id": "NqYzgIKvdm",
"type": "imports",
"links": { ... },
"attributes": {
"resource_type": "tax_categories",
"format": "csv",
"parent_resource_id": "daSWQhzjkiZ",
"status": "pending",
"started_at": null,
"completed_at": null,
"interrupted_at": null,
"inputs": "...",
"inputs_size": 2,
"errors_count": 0,
"warnings_count": 0,
"destroyed_count": 0,
"processed_count": 0,
"errors_log": {},
"warnings_log": {},
"cleanup_records": false,
"attachment_url": nil,
"created_at": "2018-01-01T12:00:00.000Z",
"updated_at": "2018-01-01T12:00:00.000Z",
"reference": null,
"reference_origin": null,
"metadata": {}
},
"meta": { ... }
}
}
To create an import of tax categories for the same tax calculator, remember to specify the tax calculator ID as the
parent_resource_id
attribute. On the other hand, specifying the tax_calculator_id
attribute for every single item of the inputs
list lets you import tax categories associated with different tax calculators all at once.For a list of all the required attributes you need to create a tax category, refer to the related section of the API reference.
CLI command
Success message
The following command imports a set of gift cards for the market identified by the ID "YlqxGhzDgJ" from a JSON file saved to a specified path:
commercelayer imports:create -t gift_cards -p YlqxGhzDgJ -i ./imports/gift_cards.json
On success, the CLI prompts this message on your terminal, separating the single imports and showing some basic information about the completed processes:
| ID | Items | Import progress | % | Status | TBP↓ | Prc. | Wrn. | Err. |
-------------------------------------------------------------------------------------------------------------
| mBxnIErwWO | 1-10000 | █████████████████████████ | 100% | completed | 0 | 10000 | 0 | 0 |
| maPBIkDKQQ | 10001-15000 | █████████████████████████ | 100% | completed | 0 | 5000 | 0 | 0 |
Import of 15000 gift cards completed.
You can inspect the status of a specific import by fetching the single import by ID and looking at the
status
attribute.When you create an import, it tries immediately to start the importing process, entering the
in_progress
status. In case the async queue is saturated, the import remains pending
until it gets a chance to be processed.Request
Response
The following request fetches a single import, the one identified by the ID "PmjlkIJzRA":
curl -g -X GET \
'https://yourdomain.commercelayer.io/api/imports/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 import object:{
"data": {
"id": "PmjlkIJzRA",
"type": "imports",
"links": { ... },
"attributes": {
"resource_type": "skus",
"format": "json",
"parent_resource_id": null,
"status": "completed",
"started_at": "2018-01-01T12:00:00.000Z",
"completed_at": "2018-01-01T12:01:00.000Z",
"interrupted_at": null,
"inputs": null,
"inputs_size": 100,
"errors_count": 5,
"warnings_count": 0,
"destroyed_count": 0,
"processed_count": 95,
"errors_log": { ... },
"warnings_log": {},
"cleanup_records": "false",
"attachment_url": "http://cl_imports.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": {}
},
"relationships": {
"events": { ... }
},
"meta": { ... }
}
}
You can also leverage Commerce Layer real-time webhooks mechanism, listen to
imports.create
, imports.start
, imports.complete
, imports.interrupt
, or imports.destroy
and react properly.When an import is completed or interrupted, import errors and warnings (related to clean-up) are reported through the
errors_count
, errors_log
, warnings_count
, and warnings_log
attributes:...
"errors_count": 5,
"warnings_count": 0,
"destroyed_count": 0,
"processed_count": 95,
"errors_log": {
"BABYONBU000000E63E7418MX": {
"name": [
"has already been taken"
]
},
"BABYONBU000000E63E7424MX": {
"shipping_category": [
"must exist"
]
},
...
},
"warnings_log": {},
...
In case you need to know at which point an import has been interrupted, you can simply sum the
processed_count
and the errors_count
attributes: the result will be the index of the last inputs
item that caused the interruption.Last modified 2mo ago