# Importing resources

Commerce Layer lets you import multiple resources in batches. To do that, you need to create a new [import resource](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/imports), 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 (at least the ones required for the specific resource to be [created](https://docs.commercelayer.io/core/creating-resources)).

{% hint style="info" %}
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.
{% endhint %}

{% hint style="warning" %}

#### Points of attention about CSV format imports

* 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](#importing-a-list-of-prices-with-price-tiers-csv)). 
* 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](#importing-a-list-of-customers-with-tags-csv)).
* When importing attributes with comma-separated string values, ensure they are correctly escaped ([see the example](#importing-a-list-of-customers-removing-associated-tags-csv)). 

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 the `inputs` list.
{% endhint %}

The process is **asynchronous** and you can poll the `status` attribute to [check the import progress](#checking-the-import-status). 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](#handling-import-errors), the `errors_count` and `errors_log` attributes are populated.

{% hint style="info" %}
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](#importing-a-list-of-orders-with-line-items-and-line-item-options-json), [price tiers](#importing-a-list-of-prices-with-price-tier-csv), [SKU list items](#importing-a-list-of-sku-lists-with-sku-list-items-json), etc.).
{% endhint %}

{% hint style="warning" %}
Some automations normally triggered on resources' creation or update (e.g. webhooks, callbacks, and most event-driven communications) might not be enabled when using imports. Read [here](#disabled-automations) for more information.
{% endhint %}

## Attachment URL

When an import is started, the data you pass within the `inputs` list is validated, compressed ([gzip](https://www.gzip.org/)), and then uploaded to an external storage service (currently [Amazon S3](https://aws.amazon.com/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.

{% hint style="info" %}
External storage service URLs expire in **5 minutes**. You need to uncompress (`gunzip`) the file in order to read the data back. If the imported data URL is expired you can just [fetch the completed import](#checking-the-import-status) to get a new working one.
{% endhint %}

## Import limits

### Maximum import size

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.

### Maximum error percentage

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.

{% hint style="info" %}
When necessary, you can disable the import interruption even if the number of its errors exceeds the 10% threshold by setting  `skip_errors` parameter to `true` (default is `false`) on the specific import.
{% endhint %}

### Concurrent imports

The maximum number of concurrent imports (i.e. imports whose status is `pending` or `in_progess`) allowed per organization is **10**.

{% hint style="info" %}
If you absolutely need to import any of the [supported resources](#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](https://github.com/commercelayer/commercelayer-cli-plugin-imports/) ([see example](#importing-more-than-10k-gift-cards-using-the-cli)).
{% endhint %}

## Supported resources

At the 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
* Stock transfers
* Tags
* Tax categories

Please find some examples of how to import them [here below](#examples).

{% hint style="info" %}
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](https://docs.commercelayer.io/core/exporting-resources).
{% endhint %}

{% content-ref url="exporting-resources" %}
[exporting-resources](https://docs.commercelayer.io/core/exporting-resources)
{% endcontent-ref %}

## Unique keys

{% hint style="info" %}
If the single resource to be imported doesn't exist it gets created, otherwise it is updated.
{% endhint %}

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` + `currency_code`
* SKUs — `code`
* Stock items — `sku_code` + `stock_location_id`
* Tags — `name`
* Tax categories — `code` + `tax_calculator_id`

{% hint style="warning" %}
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](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/orders#changing-the-order-number)). 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).
{% endhint %}

## Specifying the parent resource

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`

## Disabled automations

### Webhooks

Excluding those associated with order status change events (`orders.place`, `orders.approve`, `orders.cancel`, `orders.authorize`, `orders.void`, `orders.pay`, `orders.refund`, `orders.start_fulfilling`, `orders.cancel_fulfilling`, and `orders.fulfill`), during imports all of the [real-time webhooks](https://docs.commercelayer.io/core/real-time-webhooks) are disabled.

In case you need to leverage all the other real-time events you have to create/update resources via the related API endpoints.

### After-save callbacks

All of the resource's after-save callbacks are not executed on imports. This means that some attributes dependent on such callbacks will not be persisted (i.e. timestamps after status change or numbers set with the ID value).

In case you need to run after-save callbacks you have to make standard CRUD actions via the related API endpoints.

## Cleaning-up records

If you need to remove some resources and their associated relationships before or after importing new ones we suggest leveraging the [cleanups](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/cleanups) endpoint, making sure to use a valid [filter](https://docs.commercelayer.io/core/cleaning-resources#filtering-the-data-to-be-removed) and include the necessary relationships.

{% hint style="warning" %}
Just to be sure you can rollback, we strongly recommend to perform an [export](https://docs.commercelayer.io/core/exporting-resources) using the very same [filter](https://docs.commercelayer.io/core/exporting-resources#filtering-exported-data) before any cleanup operation.
{% endhint %}

{% content-ref url="cleaning-resources" %}
[cleaning-resources](https://docs.commercelayer.io/core/cleaning-resources)
{% endcontent-ref %}

## Examples

### Importing a list of addresses (CSV) <a href="#importing-a-list-of-addresses-csv" id="importing-a-list-of-addresses-csv"></a>

{% tabs %}
{% tab title="Request" %}
The following request creates an import with a list of addresses in CSV format:

```shell
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,george@thebeatles.co.uk\n"
      }
    }
  }'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created import object:

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

{% endtab %}
{% endtabs %}

For a list of all the required attributes you need to create an address, refer to the [related section](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/addresses/create) of the API reference.

### Importing a list of bundles (JSON)

{% tabs %}
{% tab title="Request" %}
The following request creates an import with a list of bundles in JSON format:

```shell
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"
          },
          { ... }
        ]
      }
    }
  }'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created import object:

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

{% endtab %}
{% endtabs %}

For a list of all the required attributes you need to create a bundle, refer to the [related section](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/bundles/create) of the API reference.

### Importing a list of coupons (CSV)

{% tabs %}
{% tab title="Request" %}
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:

```shell
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,george@harrison.co.uk\n"
      }
    }
   }'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created import object:

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

{% endtab %}
{% endtabs %}

For a list of all the required attributes you need to create a coupon, refer to the [related section](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/coupons/create) of the API reference.

### Importing a list of customer addresses (JSON)

{% tabs %}
{% tab title="Request" %}
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):

```shell
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": "john@example.com",
            "address_id": "gHbVCxZSdE"
          },
          {
            "customer_email": "mario@example.com",
            "address": { 
              "first_name": "Mario", 
              "last_name": "Rossi", 
              "line_1": "Viale Borgo Valsugana 7", 
              "city": "Prato", 
              "zip_code": "59100", 
              "state_code": "PO", 
              "country_code": "IT", 
              "phone": "+39 0574 933550"
            }
          },
          { ... }
        ]
      }
    }
  }'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created import object:

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

{% endtab %}
{% endtabs %}

### Importing a list of customer payment sources (JSON)

{% tabs %}
{% tab title="Request" %}
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):

```shell
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"
          },
          { ... }
        ]
      }
    }
  }'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created import object:

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
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.
{% endhint %}

For a list of all the required attributes you need to create a customer payment sources, refer to the [related section](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/customer_payment_sources/create) of the API reference.

### Importing a list of customer subscriptions (JSON)

{% tabs %}
{% tab title="Request" %}
The following request creates an import with a list of customer subscriptions in JSON format:

```shell
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": "john@example.com",
            "reference": "Marketing newsletter"
          },
          {
            "customer_email": "jane@example.com",
            "reference": "Whitepaper download"
          },
          { ... }
        ]
      }
    }
  }'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created import object:

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

{% endtab %}
{% endtabs %}

For a list of all the required attributes you need to create a customer subscription, refer to the [related section](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/customer_subscriptions/create) of the API reference.

### Importing a list of customers (CSV)

{% tabs %}
{% tab title="Request" %}
The following request creates an import with a list of customers in CSV format:

```shell
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\njohn@example.com,,\njack@example.com,secret,KngqdhAlpd\n"
      }
    }
  }'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created import object:

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

{% endtab %}
{% endtabs %}

For a list of all the required attributes you need to create a customer, refer to the [related section](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/customers/create) of the API reference.

### Importing a list of gift cards (JSON)

{% tabs %}
{% tab title="Request" %}
The following request creates an import with a list of gift cards in JSON format:

```shell
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": "john@example.com"
          },
          {
            "balance_cents": 20000,
            "currency_code": "EUR",
            "single_use": true,
            "rechargeable": false,
            "expires_at": "2025-01-01T00:00:00Z",
            "recipient_email": "jane@example.com"
          },
          { ... }
        ]
      }
    }
  }'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created import object:

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
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.
{% endhint %}

For a list of all the required attributes you need to create a gift card, refer to the [related section](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/gift_cards/create) of the API reference.

### Importing a list of orders with line items and line item options (JSON)

{% tabs %}
{% tab title="Request" %}
The following request creates an import with a list of orders with associated line items and line item options in JSON format:

<pre class="language-shell"><code class="lang-shell">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": "orders",
				"parent_resource_id": "KmjljGJzWQ",
        "inputs": [
          {
            "customer_email": "john@example.com",
            "line_items": [
              {
                "item_type": "skus",
                "name": "Black Hat Size M",
                "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": "skus",
                "name": "White T-shirt Size XL",
                "quantity": 1,
                "unit_amount_cents": 2000
              }
            ]
          },
          {
            "customer_email": "jack@example.com",
<strong>            "_archive": 1,
</strong><strong>            "status": "cancelled",
</strong><strong>            "cancelled_at": "2018-01-01T12:00:00.000Z",
</strong>            "line_items": [
              { 
                "item_type": "skus",
                "name": "Black T-Shirt Size S",
                "quantity": 2,
                "unit_amount_cents": 1500
              }
            ]
          },
          { ... }
        ]
      }
    }
  }'
</code></pre>

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created import object:

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
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.
{% endhint %}

{% hint style="warning" %}
To bypass some of the order's standard validations and avoid any issues, we strongly recommend passing the `_archive` trigger attribute when importing orders that are in a status different from `draft` and `pending`. This way, the orders will be automatically archived and you will be allowed to specify also some attributes that normally are not [updatable](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/orders/update) `status`, `payment_status`, `fulfillment_status`, `placed_at`, `approved_at`, `cacelled_at`, `payment_updated_at`, and `fulfillment_updated_at`) — just make sure to be consistent when doing that (e.g. if you define a `cancelled_at` datetime, set the order status to `cancelled` accordingly).
{% endhint %}

For a list of all the required attributes you need to create an order, refer to the [related section](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/orders/create) of the API reference.

### Importing a list of prices with price tiers (CSV)

{% tabs %}
{% tab title="Request" %}
The following request creates an import with a list of prices and the associated price tiers in CSV format:

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

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created import object:

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
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.
{% endhint %}

For a list of all the required attributes you need to create a price, refer to the [related section](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/prices/create) of the API reference. More info about price volume tiers [here](https://github.com/commercelayer/commercelayer-docs-api/blob/master/broken-reference/README.md).

### Importing a list of SKU lists with SKU list items (JSON)

{% tabs %}
{% tab title="Request" %}
The following request creates an import with a list of SKU lists with associated SKU list items in JSON format:

```shell
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",
              }
            ]
          },
          { ... }
        ]
      }
    }
  }'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created import object:

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

```

{% endtab %}
{% endtabs %}

For a list of all the required attributes you need to create an SKU list, refer to the [related section](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/sku_lists/create) of the API reference.

### Importing a list of SKU options (CSV)

{% tabs %}
{% tab title="Request" %}
The following request creates an import with a list of SKU options in CSV format:

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

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created import object:

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

```

{% endtab %}
{% endtabs %}

For a list of all the required attributes you need to create an SKU option, refer to the [related section](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/sku_options/create) of the API reference.

### Importing a list of SKUs (JSON)

{% tabs %}
{% tab title="Request" %}
The following request creates an import with a list of SKUs in JSON format:

```shell
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":"Baby's Black 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":"Baby's Black Onesie Short Sleeve with Pink Logo (18 Months)",
            "image_url":"https://img.yourdomain.com/skus/BABYONBU000000E63E74.png",
            "reference": "BABYONBU000000E63E74",
            "shipping_category_id": "zwzQeFBrNj"
          },
          { ... }
        ]
      }
    }
 }'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created import object:

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
SKUs have no [parent resource](#specifying-the-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).
{% endhint %}

For a list of all the required attributes you need to create an SKU, refer to the [related section](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/skus/create) of the API reference.

### Importing a list of stock items (CSV)

{% tabs %}
{% tab title="Request" %}
The following request creates an import with a list of stock items in CSV format:

```shell
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,_validate\nBABYONBU000000E63E7424MX,110,1\nBABYONBU000000E63E7418MX,140,1\n"
      }
    }
  }'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created import object:

```json
{
  "data": {
    "id": "YqQJGIYWjm",
    "type": "imports",
    "links": { ... },
    "attributes": {
      "resource_type": "stock_items",
      "format": "csv",
      "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": { ... }
  }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
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.
{% endhint %}

{% hint style="warning" %}
When importing stock items, existing records may be updated with inconsistent quantities: this occurs when the quantity of a stock item is less than the existing reserved stock, which is probably an overselling symptom. To avoid this scenario, we recommend passing the `_validate` trigger attribute for each of the imported inputs: in case the `quantity` is smaller than the associated `reserved_stock,` the update fails and an error is logged for further inspection.
{% endhint %}

For a list of all the required attributes you need to create a stock item, refer to the [related section](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/stock_items/create) of the API reference.

### Importing a list of stock transfers (JSON)

{% tabs %}
{% tab title="Request" %}
The following request creates an import with a list of stock transfers in JSON format:

```shell
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_transfers",
        "format": "json",
        "inputs": [
          {
            "sku_code":"BABYONBU000000E63E7424MX",
            "quantity":2,
            "origin_stock_location_id": "ondYzudReG",
            "destination_stock_location_id": "znmoyuXpYk"
          },
          {
            "sku_code":"BABYONBU000000E63E7418MX",
            "quantity":3,
            "origin_stock_location_code": "EUCOM",
            "destination_stock_location_code": "EUWHR"
          },
          { ... }
        ]
      }
    }
  }'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created import object:

```json
{
  "data": {
    "id": "YqQJGIYWjm",
    "type": "imports",
    "links": { ... },
    "attributes": {
      "resource_type": "stock_transfers",
      "format": "json",
      "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,
      "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": { ... }
  }
}
```

{% endtab %}
{% endtabs %}

For a list of all the required attributes you need to create a stock transfer, refer to the [related section](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/stock_transfers/create) of the API reference.

### Importing a list of tags (CSV)

{% tabs %}
{% tab title="Request" %}
The following request creates an import with a list of tags in CSV format:

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

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created import object:

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

```

{% endtab %}
{% endtabs %}

For a list of all the required attributes you need to create a tag, refer to the [related section](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/tags/create) of the API reference.

### Importing a list of SKUs with tags (JSON)

{% tabs %}
{% tab title="Request" %}
The following request creates an import with a list of SKUs and the associated tags in JSON format:

```shell
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": "Men's Black 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"
              }
            ]
          }
        ]
      }
    }
  }'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created import object:

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

{% endtab %}
{% endtabs %}

For a list of all the required attributes you need to create a SKU, refer to the [related section](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/skus/create) of the API reference. More info about tags [here](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/tags).

### Importing a list of customers with tags (CSV)

{% tabs %}
{% tab title="Request" %}
The following request creates an import with a list of customers and the associated tags in CSV format:

```shell
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\njohn@example.com,\"\",\"newsletter\"\njane@example.com,\"\",\"vip,black_friday\""
      }
    }
  }'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created import object:

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

{% endtab %}
{% endtabs %}

For a list of all the required attributes you need to create a customer, refer to the [related section](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/customers/create) of the API reference. More info about tags [here](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/tags).

### Importing a list of customers removing the associated tags (CSV)

{% tabs %}
{% tab title="Request" %}
The following request creates an import with a list of customers in CSV format, removing the associated tags:

```shell
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,_remove_tags\njane@example.com,\"vip,black_friday\""
      }
    }
  }'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created import object:

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

{% endtab %}
{% endtabs %}

For a list of all the required attributes you need to create a customer, refer to the [related section](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/customers/create) of the API reference. More info about tags [here](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/tags).

### Importing a list of tax categories (CSV)

{% tabs %}
{% tab title="Request" %}
The following request creates an import with a list of tax categories in CSV format:

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

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the created import object:

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
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.
{% endhint %}

For a list of all the required attributes you need to create a tax category, refer to the [related section](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/tax_categories/create) of the API reference.

### Importing more than 10K gift cards using the CLI

{% tabs %}
{% tab title="CLI command" %}
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
```

{% endtab %}

{% tab title="Success message" %}
On success, the CLI prompts this message on your terminal, separating the single imports and showing some basic information about the completed processes:

<pre><code>|     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 | 

<strong>Import of 15000 gift cards completed.
</strong></code></pre>

{% endtab %}
{% endtabs %}

## Checking the import status

You can inspect the status of a specific import by fetching the single import by ID and looking at the `status` attribute.

{% tabs %}
{% tab title="Request" %}
The following request fetches a single import, the one identified by the ID "PmjlkIJzRA":

```shell
curl -g -X GET \ 
  'https://yourdomain.commercelayer.io/api/imports/PmjlkIJzRA' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning the single import object:

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
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.
{% endhint %}

{% hint style="warning" %}
If an import 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`.&#x20;
{% endhint %}

## Webhooks for imports

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.

{% content-ref url="real-time-webhooks" %}
[real-time-webhooks](https://docs.commercelayer.io/core/real-time-webhooks)
{% endcontent-ref %}

## Handling import errors

When an import is completed or interrupted, import errors and warnings (related to [clean-up](#cleaning-up-records)) are reported through the `errors_count`, `errors_log`, `warnings_count`, and `warnings_log` attributes:

```json
...

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

...
```

{% hint style="info" %}
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.
{% endhint %}