Elastic Path · Schema
Inventories Introduction
The Inventory API allows you to manage stock for products at both organization and store levels. Stock can be optionally managed in [multiple locations](#multi-location-inventories) representing different stores or warehouses.
CommerceHeadless CommerceComposable CommerceeCommerceB2BProductsCatalogsOrdersPromotionsSubscriptionsPayments
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://raw.githubusercontent.com/api-evangelist/elastic-path/main/json-schema/inventory.json",
"title": "Inventories Introduction",
"description": "The Inventory API allows you to manage stock for products at both organization and store levels. Stock can be optionally managed in [multiple locations](#multi-location-inventories) representing different stores or warehouses.",
"version": "2.0.0",
"$defs": {
"StockType": {
"type": "string",
"enum": [
"stock"
],
"default": "stock",
"example": "stock"
},
"StockTransactionType": {
"type": "string",
"enum": [
"stock-transaction"
],
"default": "stock-transaction",
"example": "stock-transaction"
},
"MultipleProducts": {
"type": "object",
"required": [
"id"
],
"properties": {
"type": {
"type": "string",
"enum": [
"stock"
],
"default": "stock",
"example": "stock"
},
"id": {
"description": "The unique identifier of the product.",
"type": "string",
"format": "uuid",
"example": "3c78777a-cf09-4b2d-be91-a73acbf9166f"
}
}
},
"TransactionResponse": {
"type": "object",
"required": [
"id",
"type",
"attributes"
],
"properties": {
"id": {
"$ref": "#/components/schemas/UUID"
},
"type": {
"$ref": "#/components/schemas/StockTransactionType"
},
"attributes": {
"$ref": "#/components/schemas/TransactionResponseAttributes"
},
"meta": {
"$ref": "#/components/schemas/Meta"
}
}
},
"TransactionResponseAttributes": {
"type": "object",
"required": [
"action",
"product_id",
"quantity"
],
"properties": {
"action": {
"description": "The type of action performed by this transaction.\n\n- **increment** - use this when you want to make products available for purchase, for example, when you have received stock from a supplier.\n\n- **decrement** - Use this when you want to remove stock from product inventory.\n\n- **allocate** - Use this when you want to allocate stock, normally to a reseller who sells on the stock.\n\n- **deallocate** - Use this when you want to deallocate any previously allocated stock.\n",
"type": "string",
"enum": [
"increment",
"decrement",
"allocate",
"deallocate"
],
"example": "allocate",
"x-go-type": "model.TransactionAction",
"x-go-type-import": {
"name": "model",
"path": "gitlab.elasticpath.com/commerce-cloud/inventories.svc/internal/domain/model"
}
},
"product_id": {
"$ref": "#/components/schemas/UUID"
},
"quantity": {
"description": "The amount of stock affected by the stock transaction.",
"type": "integer",
"format": "int64",
"example": 5
},
"location": {
"description": "The slug of the location that the transaction should act on.",
"type": "string",
"minLength": 1,
"maxLength": 128,
"example": "milton-keynes-warehouse"
}
}
},
"StockCreate": {
"type": "object",
"required": [
"type",
"attributes"
],
"properties": {
"id": {
"$ref": "#/components/schemas/UUID"
},
"type": {
"$ref": "#/components/schemas/StockType"
},
"attributes": {
"$ref": "#/components/schemas/StockCreateAttributes"
}
}
},
"StockUpdateRequest": {
"type": "object",
"required": [
"id",
"type",
"attributes"
],
"properties": {
"id": {
"$ref": "#/components/schemas/UUID"
},
"type": {
"$ref": "#/components/schemas/StockType"
},
"attributes": {
"$ref": "#/components/schemas/StockUpdateAttributes"
}
}
},
"StockUpdateAttributes": {
"properties": {
"locations": {
"$ref": "#/components/schemas/NullableLocations"
}
}
},
"NullableLocation": {
"type": "object",
"required": [
"available"
],
"properties": {
"available": {
"type": "integer",
"format": "int64",
"example": 20
}
},
"nullable": true
},
"NullableLocations": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/NullableLocation"
}
},
"StockCreateAttributes": {
"type": "object",
"properties": {
"available": {
"type": "integer",
"format": "int64",
"example": 20
},
"locations": {
"type": "object",
"additionalProperties": {
"type": "object",
"required": [
"available"
],
"properties": {
"available": {
"type": "integer",
"format": "int64",
"example": 20
}
}
},
"example": {
"york_warehouse": {
"available": 10
},
"stevenage_warehouse": {
"available": 20
}
}
}
}
},
"StockResponse": {
"type": "object",
"required": [
"id",
"type",
"attributes",
"meta"
],
"properties": {
"id": {
"$ref": "#/components/schemas/UUID"
},
"type": {
"$ref": "#/components/schemas/StockType"
},
"attributes": {
"$ref": "#/components/schemas/StockResponseAttributes"
},
"meta": {
"$ref": "#/components/schemas/StockMeta"
}
}
},
"StockResponseAttributes": {
"type": "object",
"required": [
"available",
"total",
"allocated"
],
"properties": {
"available": {
"type": "integer",
"format": "int64",
"example": 20
},
"allocated": {
"type": "integer",
"format": "int64",
"example": 10
},
"total": {
"type": "integer",
"format": "int64",
"example": 30
},
"locations": {
"$ref": "#/components/schemas/StockLocations"
}
}
},
"StockLocations": {
"type": "object",
"additionalProperties": {
"type": "object",
"required": [
"available",
"total",
"allocated"
],
"properties": {
"available": {
"type": "integer",
"format": "int64",
"example": 20
},
"allocated": {
"type": "integer",
"format": "int64",
"example": 10
},
"total": {
"type": "integer",
"format": "int64",
"example": 30
}
}
}
},
"TransactionCreate": {
"required": [
"type",
"attributes"
],
"properties": {
"type": {
"$ref": "#/components/schemas/StockTransactionType"
},
"attributes": {
"$ref": "#/components/schemas/TransactionCreateAttributes"
}
}
},
"TransactionCreateAttributes": {
"required": [
"action",
"quantity"
],
"properties": {
"product_id": {
"$ref": "#/components/schemas/UUID"
},
"action": {
"description": "The type of action being performed by this transaction.\n\n - **increment** - use this when you want to make products available for purchase, for example, when you have received stock from a supplier.\n\n - **decrement** - Use this when you want to remove stock from product inventory.\n\n - **allocate** - Use this when you want to allocate stock, normally to a reseller who sells on the stock.\n\n - **deallocate** - Use this when you want to deallocate any previously allocated stock.\n\n - **set** - Use this when you want to set total stock to a specific value.\n",
"type": "string",
"enum": [
"increment",
"decrement",
"allocate",
"deallocate",
"set"
],
"example": "allocate",
"x-go-type": "model.TransactionAction",
"x-go-type-import": {
"name": "model",
"path": "gitlab.elasticpath.com/commerce-cloud/inventories.svc/internal/domain/model"
}
},
"quantity": {
"description": "The amount of stock affected by the stock transaction.",
"type": "integer",
"format": "int64",
"example": 5,
"minimum": 0
},
"location": {
"description": "The slug of the location that the transaction should act on.",
"type": "string",
"minLength": 1,
"maxLength": 128,
"example": "milton-keynes-warehouse"
}
}
},
"Location": {
"type": "object",
"required": [
"id",
"type",
"attributes"
],
"properties": {
"id": {
"$ref": "#/components/schemas/UUID"
},
"type": {
"$ref": "#/components/schemas/InventoryLocationType"
},
"attributes": {
"$ref": "#/components/schemas/LocationAttributes"
},
"meta": {
"$ref": "#/components/schemas/Meta"
}
}
},
"LocationAttributes": {
"required": [
"name",
"slug"
],
"properties": {
"name": {
"type": "string",
"minLength": 3,
"maxLength": 1024,
"example": "Milton Keynes Warehouse"
},
"external_ref": {
"type": "string",
"minLength": 3,
"maxLength": 1024,
"example": "mk-stock-warehouse-walnut-tree"
},
"slug": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"example": "milton-keynes-warehouse"
},
"description": {
"type": "string",
"minLength": 3,
"maxLength": 1024,
"example": "Southern dispatch location for all inventory"
},
"address": {
"type": "array",
"minItems": 1,
"maxItems": 8,
"items": {
"type": "string",
"maxLength": 1024
}
},
"geolocation": {
"$ref": "#/components/schemas/GeolocationDetails"
}
}
},
"LocationUpdateAttributes": {
"properties": {
"name": {
"type": "string",
"minLength": 3,
"maxLength": 1024,
"example": "Milton Keynes Warehouse"
},
"external_ref": {
"type": "string",
"minLength": 3,
"maxLength": 1024,
"example": "mk-stock-warehouse-walnut-tree",
"nullable": true
},
"slug": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"example": "milton-keynes-warehouse"
},
"description": {
"type": "string",
"minLength": 3,
"maxLength": 1024,
"example": "Southern dispatch location for all inventory",
"nullable": true
},
"address": {
"type": "array",
"minItems": 1,
"maxItems": 8,
"nullable": true,
"items": {
"type": "string",
"maxLength": 1024,
"nullable": true
}
},
"geolocation": {
"$ref": "#/components/schemas/GeolocationDetails"
}
}
},
"GeolocationDetails": {
"type": "object",
"nullable": true,
"description": "The longitude and latitude of a location.",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"nullable": false,
"example": 51.477928
},
"lon": {
"type": "number",
"format": "double",
"nullable": false,
"example": -0.001545
}
},
"example": {
"lat": 51.477928,
"lon": -0.001545
}
},
"LocationRequest": {
"type": "object",
"required": [
"attributes"
],
"properties": {
"type": {
"$ref": "#/components/schemas/InventoryLocationType"
},
"attributes": {
"$ref": "#/components/schemas/LocationAttributes"
}
}
},
"LocationUpdateRequest": {
"type": "object",
"required": [
"id",
"type",
"attributes"
],
"properties": {
"id": {
"$ref": "#/components/schemas/UUID"
},
"type": {
"$ref": "#/components/schemas/InventoryLocationType"
},
"attributes": {
"$ref": "#/components/schemas/LocationUpdateAttributes"
}
}
},
"InventoryLocationType": {
"type": "string",
"enum": [
"inventory_location"
],
"example": "inventory_location"
},
"UUID": {
"type": "string",
"description": "The unique identifier.",
"x-go-type": "uuid.UUID",
"x-go-type-import": {
"name": "uuid",
"path": "github.com/google/uuid"
},
"example": "00000000-0000-0000-0000-000000000000"
},
"Timestamps": {
"required": [
"created_at"
],
"properties": {
"updated_at": {
"description": "The date and time a resource was updated.",
"type": "string",
"example": "2017-01-10T11:41:19.244842Z"
},
"created_at": {
"description": "The date and time a resource was created.",
"type": "string",
"example": "2017-01-10T11:41:19.244842Z"
}
}
},
"StockMeta": {
"type": "object",
"required": [
"stock_id",
"timestamps"
],
"properties": {
"stock_id": {
"$ref": "#/components/schemas/UUID"
},
"timestamps": {
"$ref": "#/components/schemas/Timestamps"
}
}
},
"Meta": {
"type": "object",
"required": [
"timestamps"
],
"properties": {
"timestamps": {
"$ref": "#/components/schemas/Timestamps"
}
}
},
"ErrorResponse": {
"type": "object",
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"Error": {
"type": "object",
"required": [
"status",
"title"
],
"properties": {
"status": {
"type": "string",
"description": "The HTTP response code of the error.",
"example": 500
},
"title": {
"type": "string",
"description": "A brief summary of the error.",
"example": "Internal server error"
},
"detail": {
"type": "string",
"description": "Optional additional detail about the error.",
"example": "An internal error has occurred."
},
"meta": {
"type": "object",
"description": "Additional supporting meta data for the error.",
"example": {
"missing_ids": [
"e7d50bd5-1833-43c0-9848-f9d325b08be8"
]
}
}
}
},
"Links": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/Link"
}
},
"Link": {
"anyOf": [
{
"$ref": "#/components/schemas/LinkURI"
},
{
"$ref": "#/components/schemas/LinkObject"
}
]
},
"LinkURI": {
"type": "string",
"format": "uri",
"example": "http://example.com/articles/1/comments",
"nullable": true
},
"LinkObject": {
"type": "object",
"properties": {
"href": {
"type": "string",
"format": "uri",
"example": "http://example.com/articles/1/comments"
},
"title": {
"type": "string",
"example": "Comments"
},
"describedby": {
"type": "string",
"format": "uri",
"example": "http://example.com/schemas/article-comments"
}
}
},
"Import": {
"required": [
"id",
"type",
"meta",
"attributes"
],
"properties": {
"id": {
"$ref": "#/components/schemas/UUID"
},
"type": {
"$ref": "#/components/schemas/InventoriesImportType"
},
"attributes": {
"$ref": "#/components/schemas/ImportAttributes"
},
"meta": {
"$ref": "#/components/schemas/ImportMeta"
}
}
},
"ImportAttributes": {
"required": [
"status"
],
"properties": {
"external_ref": {
"$ref": "#/components/schemas/ExternalRef"
},
"status": {
"type": "string",
"description": "The status of job.\n- **pending** - Commerce has received the request but is currently busy processing other requests.\n- **started** - Commerce has started processing the job.\n- **success** - The job has successfully completed.\n- **failed** - The job has failed.\n",
"enum": [
"pending",
"started",
"success",
"failed"
],
"example": "pending",
"x-go-type": "model.JobStatus",
"x-go-type-import": {
"name": "model",
"path": "gitlab.elasticpath.com/commerce-cloud/inventories.svc/internal/domain/model"
}
}
}
},
"ImportMeta": {
"readOnly": true,
"required": [
"timestamps",
"records"
],
"properties": {
"timestamps": {
"$ref": "#/components/schemas/JobTimestamps"
},
"records": {
"$ref": "#/components/schemas/ImportRecords"
}
}
},
"ImportRecords": {
"type": "object",
"description": "You can track the number of records imported to ensure the completeness, accuracy and integrity of the import. Uploaded shows the number of records ready to be imported. However, this does not mean they are valid objects, only that they have the correct type and their JSON format is properly formatt",
"required": [
"uploaded",
"imported"
],
"properties": {
"uploaded": {
"type": "object",
"properties": {
"stock": {
"description": "The total number of product transactions uploaded.",
"type": "integer",
"example": 50000
}
},
"required": [
"stock"
]
},
"imported": {
"properties": {
"stock": {
"description": "The total number of product transactions uploaded.",
"type": "integer",
"example": 50000
}
},
"required": [
"stock"
]
}
}
},
"InventoriesImportType": {
"type": "string",
"example": "inventories_import",
"enum": [
"inventories_import"
]
},
"ExternalRef": {
"description": "A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.",
"type": "string",
"example": "abc123",
"maxLength": 2048
},
"JobTimestamps": {
"allOf": [
{
"$ref": "#/components/schemas/Timestamps"
},
{
"properties": {
"started_at": {
"description": "The date and time a job is started.",
"type": "string",
"example": "2017-01-10T11:41:19.244842Z"
},
"finished_at": {
"description": "The date and time a job finished.",
"type": "string",
"example": "2017-01-10T11:41:19.244842Z"
}
}
}
]
},
"InventoriesImportError": {
"type": "object",
"required": [
"id",
"type",
"meta"
],
"properties": {
"id": {
"$ref": "#/components/schemas/UUID"
},
"type": {
"$ref": "#/components/schemas/InventoriesImportErrorType"
},
"meta": {
"$ref": "#/components/schemas/InventoriesImportErrorMeta"
}
}
},
"InventoriesImportErrorType": {
"type": "string",
"example": "inventories_import_error",
"enum": [
"inventories_import_error"
]
},
"InventoriesImportErrorMeta": {
"type": "object",
"required": [
"timestamps",
"error",
"field",
"line_number"
],
"properties": {
"timestamps": {
"$ref": "#/components/schemas/Timestamps"
},
"error": {
"type": "string",
"example": "product name cannot be empty"
},
"field": {
"type": "string",
"example": "name"
},
"line_number": {
"type": "integer",
"description": "The line in the imported JSONL file at which the validation error occurred. Starts from 1.",
"example": 123
},
"external_ref": {
"$ref": "#/components/schemas/ExternalRef"
}
}
}
}
}