Stock API Overview

Stock API Overview

Introduction

The Stock API allows suppliers to manage stock availability per location for products listed in Ordermentum.

If you operate a single warehouse only, you do not need to use the Stock API. In this case, stock quantities can be managed directly on the product by updating the following fields:

• tracked (boolean): enables or disables stock tracking for the product
• available (integer): the available quantity for the product

Stock tracking must also be enabled in supplier settings:

The Stock API is required only when managing stock across multiple locations.

Stock is managed at the variant and location level. Stock items are created automatically and cannot be created manually via the API.

All requests require a valid bearer access token.

Base URL

All Stock API requests use the following base URL:

https://stock.ordermentum.com/v1

Authentication

All requests must include a valid bearer access token.

Required header

Authorization: Bearer <access_token>

Supplier Context Headers

Unless explicitly stated otherwise, endpoints require supplier context headers.

context-entity: supplier
context-id: <supplierId>

Sample cURL

curl -X GET "https://stock.ordermentum.com/v1/locations" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "context-entity: supplier" \
  -H "context-id: 11111111-2222-3333-4444-555555555555"

Stock Locations

Stock locations represent physical or logical warehouses where inventory is held.

Create a Stock Location

POST /locations

Request body

{
  "name": "Sydney Warehouse",
  "default": true,
  "supplierId": "11111111-2222-3333-4444-555555555555",
  "externalId": "WH-001"
}

Notes

• supplierId is required
• externalId is optional and intended for storing the corresponding location identifier from an external system (for example, an Unleashed warehouse ID)
• Supplier access is validated using the token against supplierId
• Stock quantities are not updated via the locations endpoint

List Stock Locations

GET /locations

Returns all stock locations for the supplier.

Required headers

• Authorization: Bearer <access_token>
• context-entity: supplier
• context-id: <supplierId>

Sample cURL

curl -X GET "https://stock.ordermentum.com/v1/locations" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "context-entity: supplier" \
  -H "context-id: 11111111-2222-3333-4444-555555555555"

Variant and Stock Item Identity

Each stock item maps directly to a single product variant.

The stock item ID is always the same value as the product variantId. There is no separate stock item identifier.

Whenever a stock endpoint refers to an itemId, it expects the corresponding product variantId.

Updating Stock Levels

Stock availability is updated via stock item endpoints scoped to a location and variant.

Update Stock Availability

PUT /locations/{locationId}/items/{variantId}

Required headers

• Authorization: Bearer <access_token>
• context-entity: supplier
• context-id: <supplierId>

Request body

{
  "available": 120
}

Sample cURL

curl -X PUT "https://stock.ordermentum.com/v1/locations/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/items/bbbbbbbb-cccc-dddd-eeee-ffffffffffff" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "available": 120
  }'

Product and Variant Lookup

Stock item identifiers map directly to product variants.

• itemId is the same as variantId
• productId can be obtained by querying the /variants endpoint

Key Behaviour Summary

• Stock items are created automatically
• Stock items cannot be created or deleted via the API
• Stock is managed per location and per variant
• Variant ID is used as the stock item ID
• Stock updates require a location ID and variant ID
• PUT is required for stock updates