Sale

sale API resource representing sales transactions per product-location combination in the B2C pricing application, tracking activity, returns, and revenue.

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}

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

Related Resources

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