Sale

sale API resource for the B2B pricing application representing completed sales transactions, including products sold, quantities, and final selling prices.

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}

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"
}

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"
  }'

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: Custom attributes can be added with POST /api/v2/schema/{objectName}/add-attribute, where {objectName} is this table's fully qualified warehouse name ({prefix}SALE{suffix} — for example, QP_SALE_OOTB), as returned by Describe a solution's schema
• Data Validation: All attributes are validated according to their defined data types

Related Resources

• 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