industry-department-solutions

latest

false

Supply Chain & Retail Solutions API guide

Sale

Overview

The sale resource represents completed sales transactions in the B2B pricing application. This resource stores actual sales data including products sold, quantities, and final selling prices.

→ For business context (purpose, usage notes, how this resource is used in the solution), see Sales dataset in the User Guide.

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) sales 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

sale_id (string) - Unique identifier for the sale
product_id (string) - Foreign key reference to products
region_id (string) - Geographic region of the sale
sold_at (datetime) - Timestamp of the sale

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
`sale_id`	string	Yes	No	Unique identifier for each sale. Used to identify each unique sale.
`product_id`	string	Yes	No	Unique identifier for each product. Used to join product metadata to the table and to understand which products were sold.
`customer_id`	string	Yes	Yes	Unique identifier for each customer. Used to join customer metadata to the table.
`merchant_id`	string	Yes	Yes	Unique identifier for each merchant. Used to join merchant metadata to the table.
`quote_id`	string	Yes	Yes	Unique identifier for each quote. Used to identify which quotations have converted into sales.
`sold_at`	datetime	Yes	Yes	Timestamp of sale. Used in model training to understand seasonal effects on the optimal quote price.
`quantity`	integer	Yes	Yes	Quantity of the product sold. Used to understand how much of a product was sold for KPI calculations and model training.
`selling_price`	float	Yes	Yes	Selling price for the product. Used to determine what price the product was sold for and to calculate the discount applied.
`region_id`	string	Yes	No	Unique identifier of the region. Used as a feature in model training as optimal prices vary between regions.
`price_list_id`	string	Yes	Yes	Price list used for this sale.

Relationships

Outbound References

None

Inbound References

product - Foreign key product_id references product
customer - Foreign key customer_id references customer
merchant - Foreign key merchant_id references merchant
quote_line - Foreign key quote_id references quote_line

JSON Representation

{
  "solutionName": "QP_OOTB",
  "data": [
    {
      "sale_id": "SALE-2025-001",
      "product_id": "PROD-001",
      "customer_id": "CUST-001",
      "merchant_id": "MERCH-001",
      "quote_id": "Q-2025-001",
      "sold_at": "2025-01-26T11:30:00Z",
      "quantity": 100,
      "selling_price": 189.99
    }
  ],
  "operationType": "UPSERT"
}
{
  "solutionName": "QP_OOTB",
  "data": [
    {
      "sale_id": "SALE-2025-001",
      "product_id": "PROD-001",
      "customer_id": "CUST-001",
      "merchant_id": "MERCH-001",
      "quote_id": "Q-2025-001",
      "sold_at": "2025-01-26T11:30:00Z",
      "quantity": 100,
      "selling_price": 189.99
    }
  ],
  "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": [
      {
        "sale_id": "SALE-2025-001",
        "product_id": "PROD-001",
        "customer_id": "CUST-001",
        "merchant_id": "MERCH-001",
        "quote_id": "Q-2025-001",
        "sold_at": "2025-01-26T11:30:00Z",
        "quantity": 100,
        "selling_price": 189.99
      }
    ],
    "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": [
      {
        "sale_id": "SALE-2025-001",
        "product_id": "PROD-001",
        "customer_id": "CUST-001",
        "merchant_id": "MERCH-001",
        "quote_id": "Q-2025-001",
        "sold_at": "2025-01-26T11:30:00Z",
        "quantity": 100,
        "selling_price": 189.99
      }
    ],
    "operationType": "UPSERT"
  }'

Important Notes

Foreign Key Dependencies: Can reference products, customers, merchants, and quote lines
Quote Traceability: The quote_id field links sales back to their originating quotes
Actual Pricing: Captures the final selling price which may differ from quoted or list prices
Performance Analytics: Used for sales performance analysis and pricing effectiveness
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
customer - Customer information
merchant - Merchant information
quote_line - Originating quotes
list_price - Reference pricing for comparison
product_cost - Cost data for margin analysis

Was this page helpful?

PREVIOUSRegion

NEXTInventory Management

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​