Sale Extra

sale_extra API resource capturing sales transactions broken down by product variant, used alongside sale for variant-level sales tracking.

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}

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": "MP_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/MP_SALE_EXTRA_OOTB' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "solutionName": "MP_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.

Related Resources

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