This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

Inventory

Inventory allows you to track stock quantity per SKU and optionally per supply channel.

Only one InventoryEntry can be created for a combination of an SKU and supply channel.

Representations

InventoryEntry

InventoryEntryDraft

InventoryPagedQueryResponse

InventoryEntryReference

InventoryEntryResourceIdentifier

InventoryEntry

`id` String	Unique identifier of the InventoryEntry.
`version` Int	Current version of the InventoryEntry.
`key` String	User-defined unique identifier of the InventoryEntry. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`sku` String	ProductVariant `sku` of the InventoryEntry.
`supplyChannel` ChannelReference	Channel that supplies this InventoryEntry.
`quantityOnStock` Int	Overall amount of stock (`availableQuantity` + reserved).
`availableQuantity` Int	Available amount of stock (`quantityOnStock` - reserved).
`restockableInDays` Int	How often the InventoryEntry is restocked (in days).
`expectedDelivery` DateTime	Date and time of the next restock.
`custom` CustomFields	Custom Fields of the InventoryEntry.
`createdAt` DateTime	Date and time (UTC) the InventoryEntry was initially created.
`createdBy`BETA CreatedBy	Present on resources created after 1 February 2019 except for events not tracked.
`lastModifiedAt` DateTime	Date and time (UTC) the InventoryEntry was last updated.
`lastModifiedBy`BETA LastModifiedBy	Present on resources created after 1 February 2019 except for events not tracked.

InventoryEntryDraft

`key` String	User-defined unique identifier for the InventoryEntry. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`sku` String	ProductVariant `sku` of the InventoryEntry.
`supplyChannel` ChannelResourceIdentifier	Channel that supplies this InventoryEntry.
`quantityOnStock` Int	Overall amount of stock.
`restockableInDays` Int	How often the InventoryEntry is restocked (in days).
`expectedDelivery` DateTime	Date and time of the next restock.
`custom` CustomFieldsDraft	Custom Fields of the InventoryEntry.

InventoryPagedQueryResponse

`limit` Int	Number of results requested.
`offset` Int	Number of elements skipped.
`count` Int	Actual number of results returned.
`total` Int	Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter `withTotal=false`. When the results are filtered with a Query Predicate, `total` is subject to a limit.
`results` Array of InventoryEntry	Inventory entries matching the query.

InventoryEntryReference

Reference to an InventoryEntry.

`id` String	Unique identifier of the referenced InventoryEntry.
`typeId` String	`"inventory-entry"` References an InventoryEntry.
`obj` InventoryEntry	Contains the representation of the expanded InventoryEntry. Only present in responses to requests with Reference Expansion for InventoryEntries.

InventoryEntryResourceIdentifier

ResourceIdentifier to an InventoryEntry. Either id or key is required. If both are set, an InvalidJsonInput error is returned.

`id` String	Unique identifier of the referenced InventoryEntry. Required if `key` is absent.
`key` String	User-defined unique identifier of the referenced InventoryEntry. Required if `id` is absent.
`typeId` String	`"inventory-entry"` References an InventoryEntry.

Get InventoryEntry

Get InventoryEntry by ID

GET

https://api.{region}.commercetools.com/{projectKey}/inventory/{id}

OAuth 2.0 Scopes:

view_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the InventoryEntry.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Response:

200InventoryEntryasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/inventory/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

200 Response Example: InventoryEntryjson

{
  "id": "aea4caed-accf-4667-adfe-be08ba6fdf91",
  "version": 1,
  "key": "ie-key-1",
  "sku": "sku_GIRLS_CREW_variant1_1421832124541",
  "quantityOnStock": 4,
  "availableQuantity": 4,
  "createdAt": "2015-03-11T13:36:20.720Z",
  "lastModifiedAt": "2015-03-11T13:36:20.720Z"
}

Get InventoryEntry by Key

GET

https://api.{region}.commercetools.com/{projectKey}/inventory/key={key}

OAuth 2.0 Scopes:

view_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`key` String	`key` of the InventoryEntry.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Response:

200InventoryEntryasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/inventory/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

200 Response Example: InventoryEntryjson

{
  "id": "aea4caed-accf-4667-adfe-be08ba6fdf91",
  "version": 1,
  "key": "ie-key-1",
  "sku": "sku_GIRLS_CREW_variant1_1421832124541",
  "quantityOnStock": 4,
  "availableQuantity": 4,
  "createdAt": "2015-03-11T13:36:20.720Z",
  "lastModifiedAt": "2015-03-11T13:36:20.720Z"
}

Query Inventory

GET

https://api.{region}.commercetools.com/{projectKey}/inventory

OAuth 2.0 Scopes:

view_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Query parameters:

`where` QueryPredicate	The parameter can be passed multiple times.
`/^var[.][a-zA-Z0-9]+$/` Any string parameter matching this regular expression	Predicate parameter values. The parameter can be passed multiple times.
`sort` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results requested.
`offset` Int	Number of elements skipped.
`withTotal` Boolean	Controls the calculation of the total number of query results. Set to `false` to improve query performance when the `total` is not needed.

Response:

200InventoryPagedQueryResponseasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/inventory -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

200 Response Example: InventoryPagedQueryResponsejson

{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "id": "aea4caed-accf-4667-adfe-be08ba6fdf91",
      "version": 1,
      "sku": "sku_GIRLS_CREW_variant1_1421832124541",
      "quantityOnStock": 4,
      "availableQuantity": 4,
      "createdAt": "2015-03-11T13:36:20.720Z",
      "lastModifiedAt": "2015-03-11T13:36:20.720Z"
    }
  ]
}

Check if InventoryEntry exists

Check if InventoryEntry exists by ID

HEAD

https://api.{region}.commercetools.com/{projectKey}/inventory/{id}

Checks if an InventoryEntry exists for a given id. Returns a 200 OK status if the InventoryEntry exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:

view_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the InventoryEntry.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/inventory/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if InventoryEntry exists by Key

HEAD

https://api.{region}.commercetools.com/{projectKey}/inventory/key={key}

Checks if an InventoryEntry exists for a given key. Returns a 200 OK status if the InventoryEntry exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:

view_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`key` String	`key` of the InventoryEntry.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/inventory/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if InventoryEntry exists by Query Predicate

HEAD

https://api.{region}.commercetools.com/{projectKey}/inventory

Checks if an InventoryEntry exists for a given Query Predicate. Returns a 200 OK status if any Inventory Entries match the Query Predicate, a 404 Not Found otherwise.

OAuth 2.0 Scopes:

view_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Query parameters:

where

QueryPredicate

Query Predicates on Inventory Entries are limited to Text, Enum, Boolean, Number, Date, Time, and DateTime attribute types.

The parameter can be passed multiple times.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/inventory -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Create InventoryEntry

POST

https://api.{region}.commercetools.com/{projectKey}/inventory

Produces the InventoryEntryCreated Message.

OAuth 2.0 Scopes:

manage_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Request Body:InventoryEntryDraftasapplication/json

Response:

201InventoryEntryasapplication/json

Request Example:cURL

curl https://api.{region}.commercetools.com/{projectKey}/inventory -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "sku" : "sku_GIRLS_CREW_variant1_1421832124541",
  "quantityOnStock" : 4,
  "availableQuantity" : 4
}
DATA

201 Response Example: InventoryEntryjson

{
  "id": "aea4caed-accf-4667-adfe-be08ba6fdf91",
  "version": 1,
  "key": "ie-key-1",
  "sku": "sku_GIRLS_CREW_variant1_1421832124541",
  "quantityOnStock": 4,
  "availableQuantity": 4,
  "createdAt": "2015-03-11T13:36:20.720Z",
  "lastModifiedAt": "2015-03-11T13:36:20.720Z"
}

Update InventoryEntry

Update InventoryEntry by ID

POST

https://api.{region}.commercetools.com/{projectKey}/inventory/{id}

OAuth 2.0 Scopes:

manage_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the InventoryEntry.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Request Body:

application/json

`version` Int	Expected version of the InventoryEntry on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.
`actions` Array of InventoryEntryUpdateAction	Update actions to be performed on the InventoryEntry.

Response:

200InventoryEntryasapplication/json

Request Example:cURL

curl https://api.{region}.commercetools.com/{projectKey}/inventory/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "addQuantity",
    "quantity" : 4
  } ]
}
DATA

200 Response Example: InventoryEntryjson

{
  "id": "aea4caed-accf-4667-adfe-be08ba6fdf91",
  "version": 1,
  "key": "ie-key-1",
  "sku": "sku_GIRLS_CREW_variant1_1421832124541",
  "quantityOnStock": 4,
  "availableQuantity": 4,
  "createdAt": "2015-03-11T13:36:20.720Z",
  "lastModifiedAt": "2015-03-11T13:36:20.720Z"
}

Update InventoryEntry by Key

POST

https://api.{region}.commercetools.com/{projectKey}/inventory/key={key}

OAuth 2.0 Scopes:

manage_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`key` String	`key` of the InventoryEntry.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Request Body:

application/json

`version` Int	Expected version of the InventoryEntry on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.
`actions` Array of InventoryEntryUpdateAction	Update actions to be performed on the InventoryEntry.

Response:

200InventoryEntryasapplication/json

Request Example:cURL

curl https://api.{region}.commercetools.com/{projectKey}/inventory/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "addQuantity",
    "quantity" : 4
  } ]
}
DATA

200 Response Example: InventoryEntryjson

{
  "id": "aea4caed-accf-4667-adfe-be08ba6fdf91",
  "version": 1,
  "key": "ie-key-1",
  "sku": "sku_GIRLS_CREW_variant1_1421832124541",
  "quantityOnStock": 4,
  "availableQuantity": 4,
  "createdAt": "2015-03-11T13:36:20.720Z",
  "lastModifiedAt": "2015-03-11T13:36:20.720Z"
}

Update actions

Set RestockableInDays

Add Quantity

Updates availableQuantity based on the new quantityOnStock and amount of active reservations.

`action` String	`"addQuantity"`
`quantity` Int	Value to add to `quantityOnStock`.

Example: json

{
  "action": "addQuantity",
  "quantity": 1
}

Remove Quantity

Updates availableQuantity based on the new quantityOnStock and amount of active reservations.

`action` String	`"removeQuantity"`
`quantity` Int	Value to remove from `quantityOnStock`.

Example: json

{
  "action": "removeQuantity",
  "quantity": 1
}

Change Quantity

Updates availableQuantity based on the new quantityOnStock and amount of active reservations.

`action` String	`"changeQuantity"`
`quantity` Int	Value to set for `quantityOnStock`.

Example: json

{
  "action": "changeQuantity",
  "quantity": 5
}

Set Key

`action` String	`"setKey"`
`key` String	Value to set. If empty, any existing value will be removed. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`

Example: json

{
  "action": "setKey",
  "key": "ie-key-1"
}

Set RestockableInDays

`action` String	`"setRestockableInDays"`
`restockableInDays` Int	Value to set. If empty, any existing value will be removed.

Example: json

{
  "action": "setRestockableInDays",
  "restockableInDays": 7
}

Set ExpectedDelivery

`action` String	`"setExpectedDelivery"`
`expectedDelivery` DateTime	Value to set. If empty, any existing value will be removed.

Example: json

{
  "action": "setExpectedDelivery",
  "expectedDelivery": "2015-10-21T14:00:00.000Z"
}

Set SupplyChannel

If an entry with the same sku and supplyChannel already exists, an DuplicateField error is returned.

`action` String	`"setSupplyChannel"`
`supplyChannel` ChannelResourceIdentifier	Value to set. If empty, any existing value will be removed.

Example: json

{
  "action": "setSupplyChannel",
  "supplyChannel": {
    "id": "{{supplyChannelId}}",
    "typeId": "channel"
  }
}

Set Custom Type

`action` String	`"setCustomType"`
`type` TypeResourceIdentifier	Defines the Type that extends the InventoryEntry with Custom Fields. If absent, any existing Type and Custom Fields are removed from the InventoryEntry.
`fields` FieldContainer	Sets the Custom Fields fields for the InventoryEntry.

Example: json

{
  "action": "setCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringTypeField": "TextString"
  }
}

Set CustomField

`action` String	`"setCustomField"`
`name` String	Name of the Custom Field.
`value` CustomFieldValue	If `value` is absent or `null`, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If `value` is provided, it is set for the field defined by `name`.

Example: json

{
  "action": "setCustomField",
  "name": "ExampleStringTypeField",
  "value": "TextString"
}

Delete InventoryEntry

Delete InventoryEntry by ID

DELETE

https://api.{region}.commercetools.com/{projectKey}/inventory/{id}

Produces the InventoryEntryDeleted Message.

OAuth 2.0 Scopes:

manage_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the InventoryEntry.

Query parameters:

`version` Int	Last seen version of the resource.
`expand` Expansion	The parameter can be passed multiple times.

Response:

200InventoryEntryasapplication/json

Request Example:cURL

curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/inventory/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

200 Response Example: InventoryEntryjson

{
  "id": "aea4caed-accf-4667-adfe-be08ba6fdf91",
  "version": 1,
  "key": "ie-key-1",
  "sku": "sku_GIRLS_CREW_variant1_1421832124541",
  "quantityOnStock": 4,
  "availableQuantity": 4,
  "createdAt": "2015-03-11T13:36:20.720Z",
  "lastModifiedAt": "2015-03-11T13:36:20.720Z"
}

Delete InventoryEntry by Key

DELETE

https://api.{region}.commercetools.com/{projectKey}/inventory/key={key}

Produces the InventoryEntryDeleted Message.

OAuth 2.0 Scopes:

manage_products:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`key` String	`key` of the InventoryEntry.

Query parameters:

`version` Int	Last seen version of the resource.
`expand` Expansion	The parameter can be passed multiple times.

Response:

200InventoryEntryasapplication/json

Request Example:cURL

curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/inventory/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

200 Response Example: InventoryEntryjson

{
  "id": "aea4caed-accf-4667-adfe-be08ba6fdf91",
  "version": 1,
  "key": "ie-key-1",
  "sku": "sku_GIRLS_CREW_variant1_1421832124541",
  "quantityOnStock": 4,
  "availableQuantity": 4,
  "createdAt": "2015-03-11T13:36:20.720Z",
  "lastModifiedAt": "2015-03-11T13:36:20.720Z"
}