Inventory

B2CB2BB2X
Inventory allows you to track stock quantity per SKU and optionally per supply channel.
The amount of time it takes for updates to be reflected on an InventoryEntry depends on where those changes originate. For details, see Inventory checks and consistency.
Learn more about Inventory in our self-paced Inventory modeling module.

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: 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). This value is eventually consistent with the internal SKU availability used for reservation logic, with a delay of up to 10 seconds. See Inventory checks and consistency for more information.
availableQuantity​
Int​
Available amount of stock (quantityOnStock - reserved). This value is eventually consistent with the internal SKU availability used for reservation logic, with a delay of up to 10 seconds. See Inventory checks and consistency for more information.
minCartQuantity​
Int​
Minimum quantity that can be added to a Cart. See Quantity limits.
Minimum: 1​
maxCartQuantity​
Int​
Maximum quantity that can be added to a Cart. See Quantity limits.
Minimum: 1​
restockableInDays​
Int​

How often the InventoryEntry is restocked (in days).

expectedDelivery​
DateTime​

Date and time of the next restock.

reservationExpirationInMinutes​
Int​
Expiration time of ReserveOnCart reservations associated with this InventoryEntry.
Minimum: 1​Maximum: 44640​
stockLevels​
InventoryEntryStockLevels​
Configuration of stock levels for the InventoryEntry. Corresponding Messages are triggered when the quantityOnStock reaches the configured levels.
custom​
CustomFields​

Custom Fields of the InventoryEntry.

createdAt​
DateTime​

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

createdBy​BETA
CreatedBy​

IDs and references that created the InventoryEntry.

lastModifiedAt​
DateTime​

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

lastModifiedBy​BETA
LastModifiedBy​

IDs and references that last modified the InventoryEntry.

InventoryEntryStockLevels

Stock level thresholds for an InventoryEntry that trigger Messages when stock levels reach certain points. For more information, see Stock level notifications.
reorderPoint​
Int​
When the quantityOnStock of the InventoryEntry reaches this value, an InventoryEntryReorderPoint Message is generated.
safetyStock​
Int​
When the quantityOnStock of the InventoryEntry reaches this value, an InventoryEntrySafetyStock Message is generated.

InventoryEntryDraft

key​
String​

User-defined unique identifier for the InventoryEntry.

This field is optional for backwards compatibility reasons, but we strongly recommend setting it. Keys are mandatory for importing InventoryEntries with the Import API and the Merchant Center.
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. See Inventory checks and consistency for consistency information.
minCartQuantity​
Int​
Minimum quantity that can be added to a Cart. See Quantity limits.
Minimum: 1​
maxCartQuantity​
Int​
Maximum quantity that can be added to a Cart. See Quantity limits.
Minimum: 1​
restockableInDays​
Int​

How often the InventoryEntry is restocked (in days).

expectedDelivery​
DateTime​

Date and time of the next restock.

reservationExpirationInMinutes​
Int​
Expiration time of ReserveOnCart reservations associated with this InventoryEntry.
Minimum: 1​Maximum: 44640​
stockLevels​
InventoryEntryStockLevels​
Configuration of stock levels for the InventoryEntry. Corresponding Messages are triggered when the quantityOnStock reaches the configured levels.
custom​
CustomFieldsDraft​

Custom Fields for the InventoryEntry.

InventoryPagedQueryResponse

limit​
Int​
Number of results requested.
Default: 20​Minimum: 0​Maximum: 500​
offset​
Int​
Number of elements skipped.
Default: 0​Maximum: 10000​
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​
ReferenceTypeId​
inventory-entry
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​
ReferenceTypeId​
inventory-entry

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:
200

InventoryEntry

as
application/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:
200

InventoryEntry

as
application/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 InventoryEntries

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.
sort
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​
The parameter can be passed multiple times.
limit
​
Int
​
Number of results requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int
​
Number of elements skipped.
Default: 0​
Maximum: 10000​
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.
Default: true​
var.<varName>
​
String
​
Predicate parameter values.
The parameter can be passed multiple times.
Response:
200

InventoryPagedQueryResponse

as
application/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",
      "minCartQuantity": 2,
      "maxCartQuantity": 50
    }
  ]
}

Check if InventoryEntry exists

Check if InventoryEntry exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/inventory/{id}
Checks if an InventoryEntry exists with the provided id. Returns a 200 status if the InventoryEntry exists, or a 404 status 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 with the provided key. Returns a 200 status if the InventoryEntry exists, or a 404 status 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 one or more InventoryEntries exist for the provided query predicate. Returns a 200 status if any Inventory Entries match the Query Predicate, or a 404 status 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

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

If quantity limits are provided, existing Line Items that reference a Product Variant with an SKU that matches the Inventory Entry can be affected. For more information, see Quantity limits.
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:
201

InventoryEntry

as
application/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 
{
  "key" : "ie-key-1",
  "sku" : "sku_GIRLS_CREW_variant1_1421832124541",
  "quantityOnStock" : 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:
200

InventoryEntry

as
application/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:
200

InventoryEntry

as
application/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

Incrementally updates the quantityOnStock by the specified amount. This changes the availableQuantity, based on the number of active reservations.
To set an absolute quantity value instead, use the InventoryEntryChangeQuantityAction update action.
action​
String​
"addQuantity"
quantity​
Int​
Value to add to quantityOnStock.
Example: json
{
  "action": "addQuantity",
  "quantity": 1
}

Remove Quantity

Removes a specific quantity from quantityOnStock. This changes the availableQuantity, based on the number of active reservations. You can update quantityOnStock to values below zero.
Carts with existing ReserveOnCart reservations will not be invalidated by this update action and can still be ordered.
action​
String​
"removeQuantity"
quantity​
Int​
Value to remove from quantityOnStock.
Example: json
{
  "action": "removeQuantity",
  "quantity": 1
}

Change Quantity

Sets the quantityOnStock to an absolute value. This changes the availableQuantity, based on the number of active reservations. To make an incremental change instead, use the InventoryEntryAddQuantityAction update action.
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​
Object containing the Custom Fields fields for the InventoryEntry.
Required if at least one Custom Field is defined as required in the fieldDefinitions of the referenced Type.
Example: json
{
  "action": "setCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "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": "exampleStringField",
  "value": "TextString"
}

Set Reservation Expiration In Minutes

Sets the default reservation expiration time for the Inventory Entry. This action does not affect existing reservations. To change the expiration date and time of existing reservations, see the Set Reservation Expiration In Minutes update action on the Carts API.
Produces the InventoryEntry Reservation Expiration In Minutes Set Message after a successful update.
action​
String​
"setReservationExpirationInMinutes"
reservationExpirationInMinutes​
Int​

Value to set, must be a positive integer. If empty, any existing value will be removed.

Minimum: 1​Maximum: 44640​
Example: json
{
  "action": "setReservationExpirationInMinutes",
  "reservationExpirationInMinutes": 5
}

Set Inventory Limits

When you introduce or change limits, existing Line Items in Carts might fall outside the new limits. During the next Cart update after the change:
  • A Line Item whose quantity is outside the limits is removed.
  • If a requested quantity or supply channel change exceeds a limit, the request is rejected.
Sets the inventory limits for a specific InventoryEntry. This action allows you to define minimum and maximum quantities that can be added to a Cart. For more information, see Quantity limits.
action​
String​
"setInventoryLimits"
minCartQuantity​
Int​
Sets the minimum quantity that can be added to a Cart. If the value is absent or null the inventory limit is removed.
maxCartQuantity​
Int​
Sets the maximum quantity that can be added to a Cart. If the value is absent or null the inventory limit is removed.
Example: json
{
  "action": "setInventoryLimits",
  "minCartQuantity": 2,
  "maxCartQuantity": 50
}

Set Safety Stock

Sets the safety stock level for a specific InventoryEntry. When the stock reaches this level, a corresponding InventoryEntrySafetyStock Message is generated.
action​
String​
"setSafetyStock"
quantity​
Int​
Sets the configured inventory stock level for safety stock. If the value is absent or null the configured inventory stock level is removed.
Example: json
{
  "action": "setSafetyStock",
  "quantity": 50
}

Set Reorder Point

Sets the reorder point level for a specific InventoryEntry. When the stock reaches this level, a corresponding InventoryEntryReorderPoint Message is generated.
action​
String​
"setReorderPoint"
quantity​
Int​
Sets the configured inventory stock level for reorder point. If the value is absent or null the configured inventory stock level is removed.
Example: json
{
  "action": "setReorderPoint",
  "quantity": 100
}

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:
200

InventoryEntry

as
application/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:
200

InventoryEntry

as
application/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"
}