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

id
String

Unique identifier of the InventoryEntry.

version
Int

Current version of the InventoryEntry.

key
String

User-defined unique identifier of the InventoryEntry.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
sku
String

ProductVariant sku of the InventoryEntry.

supplyChannel

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

Date and time of the next restock.

custom

Custom Fields of the InventoryEntry.

createdAt

Date and time (UTC) the InventoryEntry was initially created.

createdByBETA

Present on resources created after 1 February 2019 except for events not tracked.

lastModifiedAt

Date and time (UTC) the InventoryEntry was last updated.

lastModifiedByBETA

Present on resources created after 1 February 2019 except for events not tracked.

InventoryEntryDraft

key
String

User-defined unique identifier for the InventoryEntry.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
sku
String

ProductVariant sku of the InventoryEntry.

supplyChannel

Channel that supplies this InventoryEntry.

quantityOnStock
Int

Overall amount of stock.

restockableInDays
Int

How often the InventoryEntry is restocked (in days).

expectedDelivery

Date and time of the next restock.

custom

Custom Fields of the InventoryEntry.

InventoryPagedQueryResponse

limit
Int
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

id
String

Unique identifier of the referenced InventoryEntry.

typeId
String
"inventory-entry"

References an InventoryEntry.

Contains the representation of the expanded InventoryEntry. Only present in responses to requests with Reference Expansion for InventoryEntries.

InventoryEntryResourceIdentifier

id
String

Unique identifier of the referenced InventoryEntry. Either id or key is required.

key
String

User-defined unique identifier of the referenced InventoryEntry. Either id or key is required.

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
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
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
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
The parameter can be passed multiple times.
expand
The parameter can be passed multiple times.
limit
Int
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"
}
]
}

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
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
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 is returned.

actions

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
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 is returned.

actions

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

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: 2MaxLength: 256Pattern: ^[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

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

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"

Defines the Type that extends the InventoryEntry with Custom Fields. If absent, any existing Type and Custom Fields are removed from the InventoryEntry.

fields

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

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