Commerce Layer will be proud to sponsor the next JAMstack Conf in London — 09-10 July, 2019 🎉 Stay tuned!

API REFERENCE

Imports

Imports are very handy resources that let you asynchronously import SKUs, prices, and stock items into your organization's environment. After creating an import, you can poll the resource until the import is complete to get its reports. Import errors and warnings, if any, are reported through the errors_count, errors_log, warnings_count, and warnings_log attributes. When you import a list of resources, you can choose to delete any record that is not included in the list, by setting the cleanup_records variable to true. In case, after the import is complete you also get the number of destroyed records through the destroyed_count attribute.

The import object

An Import object is returned as part of the response body of each successful create, list, retrieve or update API call. The following table contains the list of all its fields along with their type, description and example values.

Object fields:
resource_type
string
The type of resource being imported. One of 'skus', 'prices', or 'stock_items'
Example:
skus
parent_resource_id
integer
The ID of the parent resource. It can be the 'shipping_category_id' for 'skus', the 'price_list_id' for 'prices', or the 'stock_location_id' for 'stock_items'
Example:
1234
status
string
The import job status. One of 'pending' (default), 'started', or 'completed'
Example:
started
started_at
datetime
Time at which the import was started.
Example:
2018-01-01T12:00:00.000Z
completed_at
datetime
Time at which the import was completed.
Example:
2018-01-01T12:00:00.000Z
inputs
object
Array of objects representing the resources that are being imported.
Example:
[{"code":"ABC","name":"Foo"},{"code":"DEF","name":"Bar"}]
errors_count
integer
Indicates the number of import errors, if any.
Example:
3
warnings_count
integer
Indicates the number of import warnings, if any.
Example:
1
destroyed_count
integer
Indicates the number of records that have been destroyed, if any.
Example:
99
errors_log
object
Contains the import errors, if any.
Example:
[{"code:ABC":{"name":["has already been taken"]}}]
warnings_log
object
Contains the import warnings, if any.
Example:
[{"code:ABC":["could not be deleted"]}]
cleanup_records
boolean
Indicates if the import should cleanup records that are not included in the inputs array.
Example:
true
id
integer
Unique identifier for the resource.
Example:
1234
created_at
datetime
Time at which the resource was created.
Example:
2018-01-01T12:00:00.000Z
updated_at
datetime
Time at which the resource was last updated.
Example:
2018-01-01T12:00:00.000Z
reference
string
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
object
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example:
{"foo":"bar"}

Create an import

To create a new import, send a POST request to the /api/imports endpoint, passing the resource arguments in the request body. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.

Arguments:
resource_type
required
The type of resource being imported. One of 'skus', 'prices', or 'stock_items'
Example:
skus
parent_resource_id
required
The ID of the parent resource. It can be the 'shipping_category_id' for 'skus', the 'price_list_id' for 'prices', or the 'stock_location_id' for 'stock_items'
Example:
1234
inputs
required
Array of objects representing the resources that are being imported.
Example:
[{"code":"ABC","name":"Foo"},{"code":"DEF","name":"Bar"}]
cleanup_records
Indicates if the import should cleanup records that are not included in the inputs array.
Example:
true
reference
optional
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
optional
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example:
{"foo":"bar"}
Example request:
POST /api/imports HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "imports",
    "attributes": {
      "resource_type": "skus",
      "parent_resource_id": "1234",
      "inputs": [
        {
          "code": "ABC",
          "name": "Foo"
        },
        {
          "code": "DEF",
          "name": "Bar"
        }
      ]
    }
  }
}
Example response:
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "imports",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/imports/1234"
    },
    "attributes": {
      "resource_type": "skus",
      "parent_resource_id": "1234",
      "status": "started",
      "started_at": "2018-01-01T12:00:00.000Z",
      "completed_at": "2018-01-01T12:00:00.000Z",
      "inputs": [
        {
          "code": "ABC",
          "name": "Foo"
        },
        {
          "code": "DEF",
          "name": "Bar"
        }
      ],
      "errors_count": "3",
      "warnings_count": "1",
      "destroyed_count": "99",
      "errors_log": [
        {
          "code:ABC": {
            "name": [
              "has already been taken"
            ]
          }
        }
      ],
      "warnings_log": [
        {
          "code:ABC": [
            "could not be deleted"
          ]
        }
      ],
      "cleanup_records": "true",
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
    },
    "meta": {
      "mode": "test"
    }
  }
}

List all imports

To fetch a collection of imports, send a GET request to the /api/imports endpoint.

Example request:
GET /api/imports HTTP/1.1
Accept: application/vnd.api+json
Example response:
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "1234",
      "type": "imports",
      "links": {
        "self": "https://your-brand.commercelayer.io/api/imports/1234"
      },
      "attributes": {
        "resource_type": "skus",
        "parent_resource_id": "1234",
        "status": "started",
        "started_at": "2018-01-01T12:00:00.000Z",
        "completed_at": "2018-01-01T12:00:00.000Z",
        "inputs": [
          {
            "code": "ABC",
            "name": "Foo"
          },
          {
            "code": "DEF",
            "name": "Bar"
          }
        ],
        "errors_count": "3",
        "warnings_count": "1",
        "destroyed_count": "99",
        "errors_log": [
          {
            "code:ABC": {
              "name": [
                "has already been taken"
              ]
            }
          }
        ],
        "warnings_log": [
          {
            "code:ABC": [
              "could not be deleted"
            ]
          }
        ],
        "cleanup_records": "true",
        "id": "1234",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": "ANYREFEFERNCE",
        "metadata": {
          "foo": "bar"
        }
      },
      "relationships": {
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "other": "... 24 imports (first page)"
    }
  ],
  "meta": {
    "record_count": 125,
    "page_count": 5
  },
  "links": {
    "first": "/api/imports?page[number]=1&page[size]=25",
    "prev": "/api/imports?page[number]=2&page[size]=25",
    "next": "/api/imports?page[number]=4&page[size]=25",
    "last": "/api/imports?page[number]=5&page[size]=25"
  }
}
Available filters
id q resource_type parent_resource_id status errors_count warnings_count destroyed_count reference ids started_at_from started_at_to completed_at_from completed_at_to created_at_from created_at_to updated_at_from updated_at_to
Sortable attributes
resource_type parent_resource_id status started_at completed_at errors_count warnings_count destroyed_count id created_at updated_at reference

Retrieve an import

To fetch a single import, send a GET request to the /api/imports/{{id}} endpoint, where {{id}} is the id of the resource that you want to retrieve.

Example request:
GET /api/imports/1234 HTTP/1.1
Accept: application/vnd.api+json
Example response:
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "imports",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/imports/1234"
    },
    "attributes": {
      "resource_type": "skus",
      "parent_resource_id": "1234",
      "status": "started",
      "started_at": "2018-01-01T12:00:00.000Z",
      "completed_at": "2018-01-01T12:00:00.000Z",
      "inputs": [
        {
          "code": "ABC",
          "name": "Foo"
        },
        {
          "code": "DEF",
          "name": "Bar"
        }
      ],
      "errors_count": "3",
      "warnings_count": "1",
      "destroyed_count": "99",
      "errors_log": [
        {
          "code:ABC": {
            "name": [
              "has already been taken"
            ]
          }
        }
      ],
      "warnings_log": [
        {
          "code:ABC": [
            "could not be deleted"
          ]
        }
      ],
      "cleanup_records": "true",
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
    },
    "meta": {
      "mode": "test"
    }
  }
}

Update an import

To update an existing import, send a PATCH request to the /api/imports/{{id}} endpoint, where {{id}} is the id of the resource that you want to update. The following table contains the list of all the possible arguments that you can pass with the request body, along with their type, description and examples values. Please note that all arguments are optional.

Arguments:
reference
optional
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
optional
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example:
{"foo":"bar"}
Example request:
PATCH /api/imports/1234 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "imports",
    "id": 1234,
    "attributes": {
      "reference": "ANYREFEFERNCE"
    },
    "relationships": {
    }
  }
}
Example response:
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "imports",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/imports/1234"
    },
    "attributes": {
      "resource_type": "skus",
      "parent_resource_id": "1234",
      "status": "started",
      "started_at": "2018-01-01T12:00:00.000Z",
      "completed_at": "2018-01-01T12:00:00.000Z",
      "inputs": [
        {
          "code": "ABC",
          "name": "Foo"
        },
        {
          "code": "DEF",
          "name": "Bar"
        }
      ],
      "errors_count": "3",
      "warnings_count": "1",
      "destroyed_count": "99",
      "errors_log": [
        {
          "code:ABC": {
            "name": [
              "has already been taken"
            ]
          }
        }
      ],
      "warnings_log": [
        {
          "code:ABC": [
            "could not be deleted"
          ]
        }
      ],
      "cleanup_records": "true",
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
    },
    "meta": {
      "mode": "test"
    }
  }
}

Delete an import

To delete a import, send a DELETE request to the /api/imports/{{id}} endpoint, where {{id}} is the id of the resource that you want to delete.

Example request:
DELETE /api/imports/1234 HTTP/1.1
Accept: application/vnd.api+json
Example response:
HTTP/1.1 204 No Content