industry-department-solutions

latest

false

Supply Chain & Retail Solutions API guide

Sale Extra

Overview

The sale_extra resource captures sales transactions broken down by product variant. Use it when a single product is sold in multiple variants (size, colour, pack, etc.) and your sales data needs to track each variant separately. It mirrors the structure of the sale resource but adds product_variant to the primary key so each variant's sales are a distinct row.

Resource Endpoint

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

Supported Methods

Method	Return Type	Description
POST	Response	Ingest (create/update) sale-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.)
sold_at (timestamp) - Timestamp when the sale occurred

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 sold — for example `size:L`, `colour:red`, `pack:6`. Part of the Primary Key.
`sold_at`	timestamp	Yes	No	Sale timestamp (Primary Key)
`created_at`	timestamp	Yes	Yes	Timestamp when the record was created
`sale_id`	string	Yes	Yes	Alternative sale identifier
`customer_id`	string	Yes	Yes	Customer identifier
`sales_units`	integer	Yes	No	Net units sold for this variant (after returns)
`sales_value`	float	Yes	No	Net sales value for this variant (after returns)
`return_units`	integer	Yes	No	Number of units returned
`return_value`	float	Yes	No	Total value of returned units
`demand_units`	float	Yes	Yes	Number of units demanded/ordered for this variant
`demand_value`	float	Yes	Yes	Total value of demanded units for this variant
`returned_at`	timestamp	Yes	Yes	Timestamp when items were returned
`shipped_at`	timestamp	Yes	Yes	Timestamp when items were shipped
`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",
      "sold_at": "2025-01-28T14:30:00Z",
      "created_at": "2025-01-28T14:30:00Z",
      "sale_id": "SALE-2025-0001",
      "customer_id": "CUST-12345",
      "sales_units": 2,
      "sales_value": 399.98,
      "return_units": 0,
      "return_value": 0.00,
      "demand_units": 2.0,
      "demand_value": 399.98,
      "returned_at": null,
      "shipped_at": "2025-01-28T16:00:00Z",
      "updated_at": "2025-01-28T14:30:00Z"
    }
  ],
  "operationType": "UPSERT"
}
{
  "solutionName": "QP_OOTB",
  "data": [
    {
      "product_id": "PROD-001",
      "location_id": "LOC-UK-001",
      "product_variant": "size:L",
      "sold_at": "2025-01-28T14:30:00Z",
      "created_at": "2025-01-28T14:30:00Z",
      "sale_id": "SALE-2025-0001",
      "customer_id": "CUST-12345",
      "sales_units": 2,
      "sales_value": 399.98,
      "return_units": 0,
      "return_value": 0.00,
      "demand_units": 2.0,
      "demand_value": 399.98,
      "returned_at": null,
      "shipped_at": "2025-01-28T16:00:00Z",
      "updated_at": "2025-01-28T14:30:00Z"
    }
  ],
  "operationType": "UPSERT"
}

Example Request

curl -X POST \
  'https://ingestion.peak.ai/api/v2/objects/QP_SALE_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",
        "sold_at": "2025-01-28T14:30:00Z",
        "created_at": "2025-01-28T14:30:00Z",
        "sale_id": "SALE-2025-0001",
        "customer_id": "CUST-12345",
        "sales_units": 2,
        "sales_value": 399.98,
        "return_units": 0,
        "return_value": 0.00,
        "demand_units": 2.0,
        "demand_value": 399.98,
        "returned_at": null,
        "shipped_at": "2025-01-28T16:00:00Z",
        "updated_at": "2025-01-28T14:30:00Z"
      }
    ],
    "operationType": "UPSERT"
  }'
curl -X POST \
  'https://ingestion.peak.ai/api/v2/objects/QP_SALE_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",
        "sold_at": "2025-01-28T14:30:00Z",
        "created_at": "2025-01-28T14:30:00Z",
        "sale_id": "SALE-2025-0001",
        "customer_id": "CUST-12345",
        "sales_units": 2,
        "sales_value": 399.98,
        "return_units": 0,
        "return_value": 0.00,
        "demand_units": 2.0,
        "demand_value": 399.98,
        "returned_at": null,
        "shipped_at": "2025-01-28T16:00:00Z",
        "updated_at": "2025-01-28T14:30:00Z"
      }
    ],
    "operationType": "UPSERT"
  }'

Important Notes

When to use vs sale: send rows to sale if your sales data is not broken down by variant; send rows to sale_extra when you need variant-level granularity. Don't send the same sale to both.
Foreign Key Dependencies: Requires valid product_id and location_id to exist in their respective tables.
Variant key shape: product_variant is a free-form string. Use a consistent convention across rows (e.g., attribute:value) so downstream aggregation is straightforward.
Custom Attributes: Additional custom attributes can be added using the /SALE_EXTRA/add-attribute endpoint.
Data Validation: All attributes are validated according to their defined data types.

sale - Variant-less sales transactions
product - Product information
location - Sales location
stock_extra - Stock levels broken down by variant
product_extra - Variant attributes catalog

Was this page helpful?

PREVIOUSSale

NEXTStock

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​