Stock and inventory models

location_codeStringRequired

Warehouse location code.

Example: "example"

location_idStringRequired

Warehouse location identifier.

Example: "example"

location_nameStringRequired

Warehouse location name.

Example: "example"

on_handIntegerRequired

Physical stock quantity.

Example: 10

Additional fields: No

dataCodeContentData Required

Successful response payload.

Example: {"code":"DEMO-ONE","delivery_id":null,"kind":"code","payload_id":"00000000-0000-4000-8000-000000000004","unit_id":"00000000-0000-4000-8000-000000000003"}

metaContextPageMeta | ContextMeta | PageMeta | RequestMeta Required

Response metadata.

Example: {"request_id":"example-request"}

Additional fields: No

dataDigitalUploadData Required

Successful response payload.

Example: {"consumer_id":"00000000-0000-4000-8000-000000000001","consumer_kind":"digital_import","expires_at":"2026-11-03T13:00:00Z","filename":"codes.txt","id":"00000000-0000-4000-8000-000000000002","product_id":"example","purpose":"digital_import","received_bytes":18,"sha256":"636e307039d9ca307836e9a93ea492425545bcccb6cb4ef935ab635560db828a","size_bytes":18,"status":"ready"}

metaContextPageMeta | ContextMeta | PageMeta | RequestMeta Required

Response metadata.

Example: {"request_id":"example-request"}

Additional fields: No

dataImportData Required

Successful response payload.

Example: {"delivery_id":null,"delivery_status":null,"delivery_version":null,"expected_count":2,"expires_at":"2026-11-03T13:00:00Z","id":"00000000-0000-4000-8000-000000000001","kind":"code","product_id":"example","status":"validated","validated_count":2,"validation_digest":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","version":2}

metaContextPageMeta | ContextMeta | PageMeta | RequestMeta Required

Response metadata.

Example: {"request_id":"example-request"}

Additional fields: No

dataArray <StockData > Required

Response example · ApiResponse_list_StockData__.

Example: [{"active":true,"available":5,"id":"stock_v1_WyJleGFtcGxlIiwicHJvZHVjdCIsImV4YW1wbGUiXQ","manual_reserved":2,"on_hand":10,"reserved":3,"sellable_limit":10,"target_id":"example","target_type":"product","total_reserved":5,"updated_at":"2026-01-01T12:00:00Z","version":1,"warehouse_id":"example"}]

metaContextPageMeta | ContextMeta | PageMeta | RequestMeta Required

Response metadata.

Example: {"pagination":{"has_more":false,"limit":20,"next_cursor":null},"request_id":"example"}

Additional fields: No

dataPoolData Required

Successful response payload.

Example: {"configured":true,"counts":{"available":1,"held":0,"issued":1,"planned":0,"retired":0,"staged":0},"email_mode":"order_link","enabled":true,"order_version":2,"product_id":"example","retention_days":null,"version":1}

metaContextPageMeta | ContextMeta | PageMeta | RequestMeta Required

Response metadata.

Example: {"request_id":"example-request"}

Additional fields: No

dataStockDetailData Required

Response example · StockDetailData.

Example: {"active":true,"allocations":[{"location_code":"example","location_id":"example","location_name":"example","on_hand":10}],"available":5,"id":"stock_v1_WyJleGFtcGxlIiwicHJvZHVjdCIsImV4YW1wbGUiXQ","manual_reserved":2,"on_hand":10,"reserved":3,"sellable_limit":10,"target_id":"example","target_type":"product","total_reserved":5,"updated_at":"2026-01-01T12:00:00Z","version":1,"warehouse_id":"example"}

metaContextPageMeta | ContextMeta | PageMeta | RequestMeta Required

Response metadata.

Example: {"request_id":"example"}

Additional fields: No

dataUnitsData Required

Successful response payload.

Example: {"order_version":2,"total":1,"units":[{"content_state":"present","delivery_id":"delivery-example","filename":null,"id":"00000000-0000-4000-8000-000000000003","issued_at":null,"kind":"code","location_id":"location-digital","mime_type":null,"payload_id":"00000000-0000-4000-8000-000000000004","product_id":"example","size_bytes":null,"sort_order":1,"state":"available","version":1,"warehouse_id":"warehouse-main"}]}

metaContextPageMeta | ContextMeta | PageMeta | RequestMeta Required

Response metadata.

Example: {"pagination":{"has_more":false,"limit":50,"next_cursor":null},"request_id":"example-request"}

Additional fields: No

codeStringRequired

The exact digital code. Preserve case and internal spaces.

minLength: 1maxLength: 512

Example: "DEMO-ONE"

delivery_idString | nullOptional

ID of the delivery or allocation identified by this operation.

String:format: "uuid"

Example: null

kindStringOptional

Variant of the data structure described by its allowed values.

const: "code"

Default: "code"Example: "code"

payload_idStringRequired

ID of the exact code or file content revision. It is not a public download URL.

format: "uuid"

Example: "00000000-0000-4000-8000-000000000004"

unit_idStringRequired

ID of one individual code or file in the product pool.

format: "uuid"

Example: "00000000-0000-4000-8000-000000000003"

Additional fields: No

consumer_idStringRequired

ID of the import or unit to which the upload is bound.

format: "uuid"

Example: "00000000-0000-4000-8000-000000000001"

consumer_kindStringRequired

Upload owner type: digital_import or digital_unit.

Constraints

enum

["digital_import", "digital_unit"]

Example: "digital_import"

filenameStringRequired

File

minLength: 1maxLength: 255

Example: "codes.txt"

purposeStringRequired

digital_import for TXT/CSV code lists; digital_unit for files sold individually.

Constraints

enum

["digital_unit", "digital_import"]

Example: "digital_import"

sha256StringRequired

SHA-256 (hex, 64)

Constraints

pattern

"^[0-9a-f]{64}$"

Example: "636e307039d9ca307836e9a93ea492425545bcccb6cb4ef935ab635560db828a"

size_bytesIntegerRequired

Size in bytes

minimum: 1maximum: 262144000

Example: 18

Additional fields: No

consumer_idStringRequired

ID of the import or unit to which the upload is bound.

format: "uuid"

Example: "00000000-0000-4000-8000-000000000001"

consumer_kindStringRequired

Upload owner type: digital_import or digital_unit.

Constraints

enum

["digital_import", "digital_unit"]

Example: "digital_import"

expires_atStringRequired

Expiration time of this upload or import.

format: "date-time"

Example: "2026-11-03T13:00:00Z"

filenameStringRequired

File

Example: "codes.txt"

idStringRequired

Resource identifier; preserve it as returned.

format: "uuid"

Example: "00000000-0000-4000-8000-000000000002"

product_idStringRequired

Product identifier.

Example: "example"

purposeStringRequired

digital_import for TXT/CSV code lists; digital_unit for files sold individually.

Constraints

enum

["digital_unit", "digital_import"]

Example: "digital_import"

received_bytesIntegerRequired

Uploading… · Size in bytes

Example: 18

sha256StringRequired

SHA-256 (hex, 64)

Example: "636e307039d9ca307836e9a93ea492425545bcccb6cb4ef935ab635560db828a"

size_bytesIntegerRequired

Size in bytes

Example: 18

statusStringRequired

Status accepted by this specific operation.

Example: "ready"

Additional fields: No

delivered_atStringRequired

Delivery date and time.

format: "date-time"

Example: "2026-11-03T12:00:00Z"

expected_delivery_versionIntegerRequired

Current warehouse delivery version, or 0 when creating the delivery.

minimum: 0maximum: 0

Example: 0

expected_sales_limit_versionInteger | nullOptional

Current sales-limit version; required only with publish_for_sale=true.

Integer:minimum: 0maximum: 9223372036854775807

Example: 0

expected_versionIntegerRequired

Version read before the write; a mismatch rejects the update.

minimum: 1maximum: 9223372036854775807

Example: 2

location_idStringRequired

Warehouse location identifier.

Constraints

pattern

"^[a-z0-9][a-z0-9_-]{0,62}$"

Example: "location-digital"

publish_for_saleBooleanOptional

true also increases the finite sales limit by the received quantity; false leaves that limit unchanged.

Default: falseExample: true

statusStringRequired

Status accepted by this specific operation.

Constraints

enum

["planned", "received"]

Example: "received"

validation_digestStringRequired

Opaque checksum returned by validation. Copy it unchanged into commit.

Constraints

pattern

"^[0-9a-f]{64}$"

Example: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"

warehouse_idStringRequired

Warehouse identifier.

Constraints

pattern

"^[a-z0-9][a-z0-9_-]{0,62}$"

Example: "warehouse-main"

Additional fields: No

countIntegerRequired

Exact number of units expected in this import.

minimum: 1maximum: 1000

Example: 2

kindStringRequired

Variant of the data structure described by its allowed values.

Constraints

enum

["code", "file"]

Example: "code"

Additional fields: No

delivery_idString | nullRequired

ID of the delivery or allocation identified by this operation.

Example: null

delivery_statusString | nullRequired

Warehouse delivery status: planned or received; null before commit.

Example: null

delivery_versionInteger | nullRequired

Current warehouse delivery version; use it when receiving or correcting that delivery.

Example: null

expected_countIntegerRequired

Declared number of units in the batch. Validation must accept the entire batch.

Example: 2

expires_atStringRequired

Expiration time of this upload or import.

format: "date-time"

Example: "2026-11-03T13:00:00Z"

idStringRequired

Resource identifier; preserve it as returned.

format: "uuid"

Example: "00000000-0000-4000-8000-000000000001"

kindStringRequired

Variant of the data structure described by its allowed values.

Constraints

enum

["code", "file"]

Example: "code"

product_idStringRequired

Product identifier.

Example: "example"

statusStringRequired

Status accepted by this specific operation.

Example: "validated"

validated_countIntegerRequired

Number of units accepted by the most recent successful validation.

Example: 2

validation_digestString | nullRequired

Opaque checksum returned by validation. Copy it unchanged into commit.

Example: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"

versionIntegerRequired

Resource version used for concurrency control.

Example: 2

Additional fields: No

expected_delivery_versionIntegerRequired

Current warehouse delivery version, or 0 when creating the delivery.

minimum: 1maximum: 9223372036854775807

Example: 1

expected_sales_limit_versionInteger | nullOptional

Current sales-limit version; required only with publish_for_sale=true.

Integer:minimum: 0maximum: 9223372036854775807

expected_versionIntegerRequired

Version read before the write; a mismatch rejects the update.

minimum: 1maximum: 9223372036854775807

Example: 3

publish_for_saleBooleanOptional

true also increases the finite sales limit by the received quantity; false leaves that limit unchanged.

Default: false

Additional fields: No

code_columnString | nullOptional

CSV column containing the codes; use code. Omit for TXT or file batches.

String:const: "code"

expected_versionIntegerRequired

Version read before the write; a mismatch rejects the update.

minimum: 1maximum: 9223372036854775807

Example: 1

formatString | nullOptional

Code-list format: txt or csv. File batches use upload_ids instead.

Constraints · String 1

enum

["txt", "csv"]

Example: "txt"

source_upload_idString | nullOptional

Ready private TXT/CSV upload owned by this import.

String:format: "uuid"

Example: "00000000-0000-4000-8000-000000000002"

upload_idsArray <String> | nullOptional

Ready private file uploads belonging to this import; 1–100 IDs.

Array:minItems: 1maxItems: 100

Array / Array:format: "uuid"

Additional fields: No

expected_delivery_versionIntegerRequired

Current warehouse delivery version, or 0 when creating the delivery.

minimum: 1maximum: 9223372036854775807

Example: 1

expected_order_versionIntegerRequired

Current allocation-order version of the pool, not the purchase order version.

minimum: 0maximum: 9223372036854775807

Example: 1

expected_versionIntegerRequired

Version read before the write; a mismatch rejects the update.

minimum: 1maximum: 9223372036854775807

Example: 3

reasonStringRequired

Reason recorded for the change.

minLength: 1maxLength: 500

Example: "Withdraw a revoked license"

Additional fields: No

expected_versionIntegerRequired

Version read before the write; a mismatch rejects the update.

minimum: 1maximum: 9223372036854775807

Example: 1

manual_reservedIntegerRequired

Quantity reserved manually.

minimum: 0maximum: 2147483647

Example: 1

reasonStringOptional

Reason recorded for the change.

maxLength: 500

Default: ""

Additional fields: No

email_modeStringOptional

disabled sends nothing; order_link sends an order link; code_text may also include codes.

Constraints

enum

["disabled", "order_link", "code_text"]

Default: "disabled"Example: "order_link"

enabledBooleanRequired

Whether this setting is enabled.

Example: true

expected_versionIntegerRequired

Version read before the write; a mismatch rejects the update.

minimum: 0maximum: 9223372036854775807

Example: 0

retention_daysInteger | nullOptional

null keeps files indefinitely; 1–3650 deletes them after that many days from first access. Codes are not deleted automatically.

Integer:minimum: 1maximum: 3650

Example: null

Additional fields: No

availableIntegerRequired

Number of free units that have not been reserved or issued.

Example: 1

heldIntegerRequired

Units reserved for orders but not yet issued to buyers.

Example: 0

issuedIntegerRequired

Units that have already been assigned to paid purchases.

Example: 1

plannedIntegerRequired

Units in committed deliveries that have not yet been received.

Example: 0

retiredIntegerRequired

Withdrawn units retained in warehouse history.

Example: 0

stagedIntegerRequired

Units in unfinished imports, not yet available as stock.

Example: 0

Additional fields: No

configuredBooleanRequired

Whether this product already has saved pool settings. This does not indicate plan eligibility.

Example: true

countsPoolCounts Required

Unit totals grouped by stock state; no codes or file contents.

Example: {"available":1,"held":0,"issued":1,"planned":0,"retired":0,"staged":0}

email_modeStringRequired

disabled sends nothing; order_link sends an order link; code_text may also include codes.

Constraints

enum

["disabled", "order_link", "code_text"]

Example: "order_link"

enabledBooleanRequired

Whether this setting is enabled.

Example: true

order_versionIntegerRequired

Version of the pool allocation order. Copy it into expected_order_version when reordering.

Example: 2

product_idStringRequired

Product identifier.

Example: "example"

retention_daysInteger | nullRequired

null keeps files indefinitely; 1–3650 deletes them after that many days from first access. Codes are not deleted automatically.

Example: null

versionIntegerRequired

Resource version used for concurrency control.

Example: 1

Additional fields: No

expected_versionIntegerRequired

Version read before the write; a mismatch rejects the update.

minimum: 1maximum: 9223372036854775807

Example: 1

reasonStringOptional

Reason recorded for the change.

maxLength: 500

Default: ""

sellable_limitIntegerRequired

Sales limit: -1 means unlimited and 0 disables available sales.

minimum: -1maximum: 2147483647

Example: 1

Additional fields: No

expected_versionIntegerRequired

Version read before the write; a mismatch rejects the update.

minimum: 0maximum: 9223372036854775807

Example: 0

locationsArray <LocationQuantity > Required

Warehouse locations.

minItems: 1maxItems: 100

Example: [{"location_id":"example","on_hand":1}]

reasonStringRequired

Reason recorded for the change.

minLength: 1maxLength: 500

Example: "Example"

target_idStringRequired

Identifier of the product or variant affected by the operation.

Constraints

pattern

"^[a-z0-9][a-z0-9_-]{0,62}$"

Example: "example"

target_typeStringRequired

Whether the operation concerns a product or a variant.

Constraints

enum

["product", "variant"]

Example: "product"

warehouse_idStringRequired

Warehouse identifier.

Constraints

pattern

"^[a-z0-9][a-z0-9_-]{0,62}$"

Example: "example"

Additional fields: No

expected_versionIntegerRequired

Version read before the write; a mismatch rejects the update.

minimum: 1maximum: 9223372036854775807

Example: 1

locationsArray <LocationQuantity > Required

Warehouse locations.

minItems: 1maxItems: 100

Example: [{"location_id":"example","on_hand":1}]

reasonStringRequired

Reason recorded for the change.

minLength: 1maxLength: 500

Example: "Example"

Additional fields: No

activeBooleanRequired

Whether the resource is active.

Example: true

availableInteger | nullRequired

Quantity available for sale; null represents an unbounded amount.

Example: 5

idStringRequired

Resource identifier; preserve it as returned. (StockData).

Example: "stock_v1_WyJleGFtcGxlIiwicHJvZHVjdCIsImV4YW1wbGUiXQ"

manual_reservedIntegerRequired

Quantity reserved manually.

Example: 2

on_handIntegerRequired

Physical stock quantity.

Example: 10

reservedIntegerRequired

Quantity reserved by orders.

Example: 3

sellable_limitIntegerRequired

Sales limit: -1 means unlimited and 0 disables available sales.

Example: 10

target_idStringRequired

Identifier of the product or variant affected by the operation.

Example: "example"

target_typeStringRequired

Whether the operation concerns a product or a variant.

Constraints

enum

["product", "variant"]

Example: "product"

total_reservedIntegerRequired

Total reserved quantity.

Example: 5

updated_atStringRequired

Most recent update time.

format: "date-time"

Example: "2026-01-01T12:00:00Z"

versionIntegerRequired

Resource version used for concurrency control.

Example: 1

warehouse_idStringRequired

Warehouse identifier.

Example: "example"

Additional fields: No

activeBooleanRequired

Whether the resource is active.

Example: true

allocationsArray <AllocationData > Required

Quantities assigned to warehouse locations.

Example: [{"location_code":"example","location_id":"example","location_name":"example","on_hand":10}]

availableInteger | nullRequired

Quantity available for sale; null represents an unbounded amount.

Example: 5

idStringRequired

Resource identifier; preserve it as returned. (StockDetailData).

Example: "stock_v1_WyJleGFtcGxlIiwicHJvZHVjdCIsImV4YW1wbGUiXQ"

manual_reservedIntegerRequired

Quantity reserved manually.

Example: 2

on_handIntegerRequired

Physical stock quantity.

Example: 10

reservedIntegerRequired

Quantity reserved by orders.

Example: 3

sellable_limitIntegerRequired

Sales limit: -1 means unlimited and 0 disables available sales.

Example: 10

target_idStringRequired

Identifier of the product or variant affected by the operation.

Example: "example"

target_typeStringRequired

Whether the operation concerns a product or a variant.

Constraints

enum

["product", "variant"]

Example: "product"

total_reservedIntegerRequired

Total reserved quantity.

Example: 5

updated_atStringRequired

Most recent update time.

format: "date-time"

Example: "2026-01-01T12:00:00Z"

versionIntegerRequired

Resource version used for concurrency control.

Example: 1

warehouse_idStringRequired

Warehouse identifier.

Example: "example"

Additional fields: No

content_stateStringRequired

Payload state: present, deleting or deleted. A history row may remain after deletion.

Example: "present"

delivery_idString | nullRequired

ID of the delivery or allocation identified by this operation.

Example: "delivery-example"

filenameString | nullRequired

File

Example: null

idStringRequired

Resource identifier; preserve it as returned.

format: "uuid"

Example: "00000000-0000-4000-8000-000000000003"

issued_atString | nullRequired

Time the unit was first issued, or null while it has not been issued.

String:format: "date-time"

Example: null

kindStringRequired

Variant of the data structure described by its allowed values.

Constraints

enum

["file", "code"]

Example: "code"

location_idString | nullRequired

Warehouse location identifier.

Example: "location-digital"

mime_typeString | nullRequired

Media content type.

Example: null

payload_idStringRequired

ID of the exact code or file content revision. It is not a public download URL.

format: "uuid"

Example: "00000000-0000-4000-8000-000000000004"

product_idStringRequired

Product identifier.

Example: "example"

size_bytesInteger | nullRequired

Size in bytes

Example: null

sort_orderIntegerRequired

Position in the ordered collection.

Example: 1

stateStringRequired

Status

Example: "available"

versionIntegerRequired

Resource version used for concurrency control.

Example: 1

warehouse_idString | nullRequired

Warehouse identifier.

Example: "warehouse-main"

Additional fields: No

expected_versionIntegerRequired

Version read before the write; a mismatch rejects the update.

minimum: 1

Example: 1

reasonStringRequired

Reason recorded for the change.

minLength: 1maxLength: 500

Example: "Withdraw a revoked license"

Additional fields: No

expected_order_versionIntegerRequired

Current allocation-order version of the pool, not the purchase order version.

minimum: 1

Example: 1

unit_idsArray <String> Required

Every unit from the unfiltered page, arranged in the requested order.

minItems: 2maxItems: 100

Array:format: "uuid"

Example: ["00000000-0000-4000-8000-000000000008","00000000-0000-4000-8000-000000000003"]

window_cursorString | nullOptional

Cursor identifying the complete unfiltered page being reordered; null for the first page.

String:maxLength: 1024

Additional fields: No

codeString | nullOptional

The exact digital code. Preserve case and internal spaces.

String:minLength: 1maxLength: 512

Example: "SYNTHETIC-REPLACEMENT"

expected_versionIntegerRequired

Version read before the write; a mismatch rejects the update.

minimum: 1

Example: 1

reasonStringRequired

Reason recorded for the change.

minLength: 1maxLength: 500

Example: "Replace an invalid activation code"

upload_idString | nullOptional

Resource identifier; preserve it as returned. · upload_id

String:format: "uuid"

Additional fields: No

order_versionIntegerRequired

Version of the pool allocation order. Copy it into expected_order_version when reordering.

Example: 2

totalIntegerRequired

Total amount.

Example: 1

unitsArray <UnitData > Required

Page of unit metadata. Codes require a separate authorized content request.

Example: [{"content_state":"present","delivery_id":"delivery-example","filename":null,"id":"00000000-0000-4000-8000-000000000003","issued_at":null,"kind":"code","location_id":"location-digital","mime_type":null,"payload_id":"00000000-0000-4000-8000-000000000004","product_id":"example","size_bytes":null,"sort_order":1,"state":"available","version":1,"warehouse_id":"warehouse-main"}]

Additional fields: Yes