industry-department-solutions

latest

false

Supply Chain & Retail Solutions API guide

Stock Extra

Overview

The stock_extra resource captures inventory levels broken down by product variant. Use it alongside sale_extra when your sales data tracks variants and you need matching variant-level stock counts. Mirrors the structure of stock but adds product_variant to the primary key.

Resource Endpoint

/api/v2/ingest/object/{prefix}STOCK_EXTRA{suffix}
/api/v2/ingest/object/{prefix}STOCK_EXTRA{suffix}

Supported Methods

Method	Return Type	Description
POST	Response	Ingest (create/update) stock-extra records via UPSERT operation

Request Headers

Header	Required	Description
`Authorization`	Yes	Your Personal Access Token (PAT) from platform.peak.ai
`Content-Type`	Yes	Must be `application/json`

Properties

Primary Keys

product_id (string) - Foreign key reference to products
location_id (string) - Foreign key reference to locations
product_variant (string) - Variant identifier (size / colour / pack / etc.)
stock_date_at (date) - Date for the stock snapshot

Attributes

About Required + Nullable: every attribute key must appear in each payload (Required: Yes). Nullable: Yes means the value can be null when you don't have data; Nullable: No means a non-null value is required. See Schema definition structure for the underlying rules.

Attribute	Data Type	Required	Nullable	Description
`product_id`	string	Yes	No	Product identifier (Primary Key, Foreign Key)
`location_id`	string	Yes	No	Location identifier (Primary Key, Foreign Key)
`product_variant`	string	Yes	No	Variant of the product (e.g., `size:L`, `colour:red`). Part of the Primary Key.
`stock_date_at`	date	Yes	No	Stock snapshot date (Primary Key)
`created_at`	timestamp	Yes	Yes	Timestamp when the record was created
`stock_id`	string	Yes	Yes	Alternative stock record identifier
`stock_units`	integer	Yes	No	Number of units in stock for this variant
`updated_at`	timestamp	Yes	Yes	Timestamp when the record was last updated

Relationships

Outbound References

None

Inbound References

product - Foreign key product_id references product
location - Foreign key location_id references location

JSON Representation

{
  "solutionName": "QP_OOTB",
  "data": [
    {
      "product_id": "PROD-001",
      "location_id": "LOC-UK-001",
      "product_variant": "size:L",
      "stock_date_at": "2025-01-28",
      "created_at": "2025-01-28T00:00:00Z",
      "stock_id": "STK-2025-001",
      "stock_units": 120,
      "updated_at": "2025-01-28T10:00:00Z"
    }
  ],
  "operationType": "UPSERT"
}
{
  "solutionName": "QP_OOTB",
  "data": [
    {
      "product_id": "PROD-001",
      "location_id": "LOC-UK-001",
      "product_variant": "size:L",
      "stock_date_at": "2025-01-28",
      "created_at": "2025-01-28T00:00:00Z",
      "stock_id": "STK-2025-001",
      "stock_units": 120,
      "updated_at": "2025-01-28T10:00:00Z"
    }
  ],
  "operationType": "UPSERT"
}

Example Request

curl -X POST \
  'https://ingestion.peak.ai/api/v2/objects/QP_STOCK_EXTRA_OOTB' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "solutionName": "QP_OOTB",
    "data": [
      {
        "product_id": "PROD-001",
        "location_id": "LOC-UK-001",
        "product_variant": "size:L",
        "stock_date_at": "2025-01-28",
        "created_at": "2025-01-28T00:00:00Z",
        "stock_id": "STK-2025-001",
        "stock_units": 120,
        "updated_at": "2025-01-28T10:00:00Z"
      }
    ],
    "operationType": "UPSERT"
  }'
curl -X POST \
  'https://ingestion.peak.ai/api/v2/objects/QP_STOCK_EXTRA_OOTB' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "solutionName": "QP_OOTB",
    "data": [
      {
        "product_id": "PROD-001",
        "location_id": "LOC-UK-001",
        "product_variant": "size:L",
        "stock_date_at": "2025-01-28",
        "created_at": "2025-01-28T00:00:00Z",
        "stock_id": "STK-2025-001",
        "stock_units": 120,
        "updated_at": "2025-01-28T10:00:00Z"
      }
    ],
    "operationType": "UPSERT"
  }'

Important Notes

When to use vs stock: send rows to stock if you don't track variant-level inventory; send to stock_extra when variant-level stock is required. Don't double-count by sending the same physical inventory to both.
Variant convention: keep the product_variant string consistent with what you use in sale_extra — downstream consumers join the two on the same (product_id, location_id, product_variant) tuple.
Foreign Key Dependencies: Requires valid product_id and location_id to exist in their respective tables.
Custom Attributes: Additional custom attributes can be added using the /STOCK_EXTRA/add-attribute endpoint.
Data Validation: All attributes are validated according to their defined data types.

stock - Variant-less stock levels
sale_extra - Variant-level sales (paired use)
product - Product information
location - Stock location

Was this page helpful?

PREVIOUSStock

NEXTTax

Supply Chain & Retail Solutions API guide

Overview​

Resource Endpoint​

Supported Methods​

Request Headers​

Properties​

Primary Keys​

Attributes​

Relationships​

Outbound References​

Inbound References​

JSON Representation​

Example Request​

Important Notes​

Related Resources​