Skip to main content

​
Overview

This document explains how to send order data with pricing and discount information to our system. You’ll need to provide the original price, the paid price, and promotion details for each product. We calculate the discount amount from the prices you provide. Important: We track two types of discounts separately:
  • Product-level discounts (sales, promotions) - you provide promotionAmount (line level)
  • Order-level discounts (voucher codes, cart promotions) - you provide voucherDiscount (order level)

​
Quick start

​
What you provide

For each product in an order, provide:
  • originalPrice - Original price per unit (before any discounts). Including tax, but excluding order level discounts.
  • paidPrice - Price per unit paid by the customer before any order-level discounts. Including tax.
  • promotionAmount - The product-level discount/promotion amount (optional)
  • promotionId - Identifier for the promotion (optional)
  • promotionType - Type of promotion (optional)
For the order level:
  • voucherDiscount - The order-level discount amount (optional)
  • voucher - The voucher code used (optional)
  • voucherType - Type of voucher (optional)

​
What we calculate

We automatically calculate:
  • discount = originalPrice - paidPrice
  • Order totals based on the formula: sum(originalPrice - promotionAmount) - voucherDiscount + shipping = total
Note: You don’t need to calculate or provide the discount field - we derive it from the prices you provide. Both originalPrice and paidPrice include tax.

​
Discount types

​
Product-level discounts

Promotional discounts applied directly to a product’s price (e.g., sale items, markdowns). Example: Jacket originally $219.00, on sale for $175.20
  • originalPrice: $219.00
  • paidPrice: $175.20 (includes tax)
  • promotionAmount: $43.80

​
Order-level discounts

Discounts applied to the entire order through voucher codes or cart-wide promotional rules. Example: Additional 10% off with code “SAVE10” Important: These are tracked in the voucherDiscount field at the order level, NOT in the product line promotionAmount field.

​
Combined discounts

Both types can stack on the same item, but they’re tracked separately: Example:
  • originalPrice: €59.90 (list price)
  • paidPrice: €47.92 (after 20% product-level sale, including tax)
  • promotionAmount: €11.98 (product-level discount only)
  • voucher: “SAVE10” (order-level discount code)
  • voucherDiscount: €4.79 (order-level discount, tracked at order level)

​
Free items

Items given at no charge should be recorded with 100% product-level promotion. Example:
  • originalPrice: €29.90
  • paidPrice: €0.00
  • promotionAmount: €29.90 (100% off)

​
How to provide pricing and promotion information

When preparing your order data, provide the following information:

​
For product-level promotions (line level):

For each product line item, provide:
  1. originalPrice - Original price per unit (before any discounts). Including tax, but excluding order level discounts.
  2. paidPrice - Price after product-level discounts (sales, markdowns), including tax
  3. promotionAmount - The amount of the product-level discount (if applicable)
  4. promotionId - Identifier for the promotion (optional)
  5. promotionType - Type of promotion, e.g., “percentage”, “fixed” (optional)
Example:
  • originalPrice: $100
  • Sale discount: 20% off
  • paidPrice: $80 (after discount, including tax)
  • promotionAmount: $20
Important: The promotionAmount field should ONLY contain product-level discounts (promotional sales, markdowns, etc.). Do NOT include order-level discounts here. Note: We’ll automatically calculate discount = originalPrice - paidPrice on our end.

​
For order-level discounts (order level):

Order-level discounts from voucher codes or cart promotions should be provided at the order level:
  • voucher - The discount code used (e.g., “SAVE10”)
  • voucherDiscount - The total discount amount from the voucher code
  • voucherType - Type of discount (e.g., “percentage”, “fixed”)

​
Required data format

For each product in an order, you must provide: 
{
  "id": "SKU123",
  "name": "Product Name",
  "quantity": 1,
  "originalPrice": 219000000,
  "paidPrice": 175200000,
  "promotionAmount": 43800000,
  "promotionId": "summer-sale-2024",
  "promotionType": "percentage",
  "currency": "USD",
  "tax": 0
}
Required Fields:
  • id - Product SKU or unique identifier
  • name - Product name
  • quantity - Number of units purchased
  • originalPrice - Original price per unit (before any discounts). Including tax, but excluding order level discounts.
  • paidPrice - Price per unit paid by the customer before any order-level discounts. Including tax.
  • currency - Transaction currency (e.g., “USD”, “EUR”)
  • tax - Tax amount charged (already included in both originalPrice and paidPrice)
Optional Fields:
  • promotionAmount - Product-level discount amount (if applicable)
  • promotionId - Identifier for the promotion (if applicable)
  • promotionType - Type of promotion, e.g., “percentage”, “fixed” (if applicable)
Pricing Validation: Ensure that originalPrice - promotionAmount = paidPrice Critical Notes:
  • Both originalPrice and paidPrice include tax
  • promotionAmount contains ONLY product-level discounts (sales, markdowns)
  • Order-level discounts (voucher codes) are tracked separately in voucherDiscount at the order level and should NOT be included in the promotionAmount field
  • You do NOT need to provide a discount field - we calculate it as discount = originalPrice - paidPrice

​
Discount codes (order-level discounts)

If voucher codes or cart-wide discount codes were used, provide them at the order level: 
{
  "orderId": "ORD-12345",
  "voucher": "SAVE10",
  "voucherDiscount": 100.00,
  "voucherType": "percentage",
  "items": [...]
}
Order-Level Fields:
  • voucher - The discount code used (e.g., “SAVE10”, “WELCOME20”)
  • voucherDiscount - Total discount amount from the voucher code (for the entire order)
  • voucherType - Type of discount (“percentage”, “fixed”, etc.)
Critical: Order-level discount amounts should be provided in the voucherDiscount field at the order level, NOT in individual product promotionAmount fields. The promotionAmount field is reserved for product-level discounts only.

​
How to handle tax

All prices should include tax. The paidPrice field should always include tax, and you should specify the tax portion separately in the tax field.

​
Tax included in customer-facing price

When tax is included in the displayed price (e.g., in Europe):
  • The customer sees one price throughout checkout
  • Provide the paidPrice including tax
  • Specify the tax portion in the tax field
Example:
  • Customer sees: €47.92
  • paidPrice: €47.92 (includes tax)
  • tax: €8.00 (tax portion already included)
  • Net price: €39.92

​
Tax added at checkout

When tax is displayed separately at checkout (e.g., in the US):
  • The customer sees tax added as a separate line
  • Still provide the paidPrice as the total including tax
  • Specify the tax amount in the tax field
Example:
  • Product price shown: $159.20
  • Tax added at checkout: $12.74
  • paidPrice: $171.94 (includes the tax)
  • tax: $12.74 (tax portion)

​
Multi-item orders

When submitting orders with multiple items, provide pricing data for each item independently. Remember that product-level and order-level discounts are tracked separately. Example Order Structure:
  • Item 1: Regular price, no discounts
    • originalPrice = paidPrice, no promotionAmount field (or set to 0)
  • Item 2: On sale (product-level discount only)
    • promotionAmount field contains the sale discount
  • Item 3: On sale + voucher code used on order
    • promotionAmount field contains only the product sale discount
    • Order-level voucher discount tracked in voucherDiscount at order level
  • Item 4: Free gift (100% product-level discount)
    • paidPrice = 0, promotionAmount = originalPrice
Note: If a voucher code applies to the entire order, provide the voucher information once at the order level, not repeated for each product.

​
Edge cases and examples

​
No discount applied

When an item has no product-level discount, you can omit the promotionAmount field (or set it to 0). The paidPrice will equal originalPrice (plus tax if applicable): 
{
  "originalPrice": 359990000,
  "paidPrice": 359990000,
  "tax": 0
}
Note: If an order-level voucher code is applied, it’s tracked separately in voucherDiscount at the order level, not in the product’s promotionAmount field.

​
Multiple quantities

When a customer purchases multiple units of the same item, provide the per-unit pricing: Example:
  • Customer buys 3 items at $50 each (original price)
  • 20% product-level sale applied
  • Per unit values:
    • originalPrice = $50
    • paidPrice = $40 (after sale, including tax)
    • promotionAmount = $10 (product discount per unit)
    • quantity = 3
  • Total product-level savings: $30

​
Complete order example

Here’s a complete order with multiple discount types (showing what you provide): 
{
  "orderId": "ORD-12345",
  "voucher": "SAVE10",
  "voucherDiscount": 17.52,
  "voucherType": "percentage",
  "items": [
    {
      "id": "SKU001",
      "name": "Jacket",
      "productId": "PROD-001",
      "variantNo": "VAR-001",
      "quantity": 1,
      "originalPrice": 219.00,
      "paidPrice": 175.20,
      "promotionAmount": 43.80,
      "promotionId": "summer-sale-2024",
      "promotionType": "percentage",
      "tax": 0,
      "currency": "USD"
    }
  ]
}
What You Provide:
  • originalPrice: $219.00
  • paidPrice: $175.20
  • promotionAmount: $43.80 (product-level promotion)
  • voucherDiscount: $17.52 (order-level discount)
What We Calculate:
  • discount = originalPrice - paidPrice = $219.00 - $175.20 = $43.80
Customer’s Journey:
  1. Original price: $219.00
  2. After product promotion: $175.20 (saved $43.80)
  3. After order voucher: $157.68 (additional $17.52 off)
  4. Total savings: $61.32