industry-department-solutions

latest

false

Supply Chain & Retail Solutions API guide

Sale

Overview

The sale resource represents sales transactions for products at specific locations in the B2C pricing application. This resource tracks sales activity, returns, and revenue details.

Resource Endpoint

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

Supported Methods

Method	Return Type	Description
POST	Response	Ingest (create/update) sale 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

location_id (string) - Foreign key reference to locations
product_id (string) - Foreign key reference to products
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
`location_id`	string	Yes	No	Location identifier (Primary Key, Foreign Key)
`product_id`	string	Yes	No	Product identifier (Primary Key, Foreign Key)
`sold_at`	timestamp	Yes	No	Sale timestamp (Primary Key)
`customer_id`	string	Yes	Yes	Customer identifier
`sale_id`	string	Yes	Yes	Alternative sale identifier
`demand_units`	float	Yes	Yes	Number of units demanded/ordered
`demand_value`	float	Yes	Yes	Total value of demanded units
`return_units`	integer	Yes	No	Number of units returned
`return_value`	float	Yes	No	Total value of returned units
`sales_units`	integer	Yes	No	Net units sold (after returns)
`sales_value`	float	Yes	No	Net sales value (after returns)
`created_at`	timestamp	Yes	Yes	Timestamp when the record was created
`updated_at`	timestamp	Yes	Yes	Timestamp when the record was last updated
`returned_at`	timestamp	Yes	Yes	Timestamp when items were returned
`shipped_at`	timestamp	Yes	Yes	Timestamp when items were shipped

Relationships

Outbound References

None

Inbound References

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

JSON Representation

{
  "solutionName": "QP_OOTB",
  "data": [
    {
      "location_id": "LOC-UK-001",
      "product_id": "PROD-001",
      "sold_at": "2025-01-28T14:30:00Z",
      "customer_id": "CUST-12345",
      "sale_id": "SALE-2025-0001",
      "demand_units": 2.0,
      "demand_value": 399.98,
      "return_units": 0,
      "return_value": 0.00,
      "sales_units": 2,
      "sales_value": 399.98,
      "created_at": "2025-01-28T14:30:00Z",
      "updated_at": "2025-01-28T14:30:00Z",
      "returned_at": null,
      "shipped_at": "2025-01-28T16:00:00Z"
    }
  ],
  "operationType": "UPSERT"
}
{
  "solutionName": "QP_OOTB",
  "data": [
    {
      "location_id": "LOC-UK-001",
      "product_id": "PROD-001",
      "sold_at": "2025-01-28T14:30:00Z",
      "customer_id": "CUST-12345",
      "sale_id": "SALE-2025-0001",
      "demand_units": 2.0,
      "demand_value": 399.98,
      "return_units": 0,
      "return_value": 0.00,
      "sales_units": 2,
      "sales_value": 399.98,
      "created_at": "2025-01-28T14:30:00Z",
      "updated_at": "2025-01-28T14:30:00Z",
      "returned_at": null,
      "shipped_at": "2025-01-28T16:00:00Z"
    }
  ],
  "operationType": "UPSERT"
}

Example Request

curl -X POST \
  'https://ingestion.peak.ai/api/v2/objects/QP_SALE_OOTB' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "solutionName": "QP_OOTB",
    "data": [
      {
        "location_id": "LOC-UK-001",
        "product_id": "PROD-001",
        "sold_at": "2025-01-28T14:30:00Z",
        "customer_id": "CUST-12345",
        "sale_id": "SALE-2025-0001",
        "demand_units": 2.0,
        "demand_value": 399.98,
        "return_units": 0,
        "return_value": 0.00,
        "sales_units": 2,
        "sales_value": 399.98,
        "created_at": "2025-01-28T14:30:00Z",
        "updated_at": "2025-01-28T14:30:00Z",
        "returned_at": null,
        "shipped_at": "2025-01-28T16:00:00Z"
      }
    ],
    "operationType": "UPSERT"
  }'
curl -X POST \
  'https://ingestion.peak.ai/api/v2/objects/QP_SALE_OOTB' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "solutionName": "QP_OOTB",
    "data": [
      {
        "location_id": "LOC-UK-001",
        "product_id": "PROD-001",
        "sold_at": "2025-01-28T14:30:00Z",
        "customer_id": "CUST-12345",
        "sale_id": "SALE-2025-0001",
        "demand_units": 2.0,
        "demand_value": 399.98,
        "return_units": 0,
        "return_value": 0.00,
        "sales_units": 2,
        "sales_value": 399.98,
        "created_at": "2025-01-28T14:30:00Z",
        "updated_at": "2025-01-28T14:30:00Z",
        "returned_at": null,
        "shipped_at": "2025-01-28T16:00:00Z"
      }
    ],
    "operationType": "UPSERT"
  }'

Important Notes

Foreign Key Dependencies: Requires valid product_id and location_id to exist in their respective tables
Return Tracking: Captures both gross sales and returns for net sales calculation
Multi-Metric: Tracks both units and values for demand, returns, and net sales
Fulfillment Tracking: Monitors when items were shipped and returned
Custom Attributes: Additional custom attributes can be added using the /SALE/add-attribute endpoint
Data Validation: All attributes are validated according to their defined data types

product - Product information
location - Sales location
product_pricing_daily - Pricing at time of sale
stock - Stock impact from sales

Was this page helpful?

PREVIOUSPurchase Order

NEXTSale Extra

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​