Order Pricing
Overview
This document explains how to interpret the pricing and calculation fields provided in order data.
Order Amount Fields
| Field | Description |
|---|---|
subtotal | Amount of all items in the order prior to tax and/or discounts |
tax | Amount of taxes charged to the customer and paid to the merchant (excludes delivery-fee tax — see delivery_fee_taxes) |
tax_withheld_by_dsp | Amount of taxes charged to the customer and paid to the DSP |
restaurant_tip | Amount of tip provided to the store |
driver_tip | Amount of tip provided to the driver |
delivery_fee | Amount of fees provided to the delivery courier |
delivery_fee_taxes | Tax on the delivery fee (only on merchant_managed_delivery orders; absent when zero); not included in tax |
service_charge | Diner-paid service charge that goes to the merchant (merchant revenue) |
dsp_fees | Diner-paid fee(s) that are not merchant revenue — collected at fulfillment and remitted to the DSP/platform |
amount_paid_by_other_methods | Portion of the order already settled electronically (e.g. credits/card) when the remainder is due in cash |
cash_amount_due | Amount to collect from the customer in cash at fulfillment (only on unpaid/cash orders) — see Cash Orders |
Currency Format
All pricing values are provided in the lowest denomination of the currency specified for the store.
For example:
- USD: Values are in cents (e.g.,
2500= $25.00) - EUR: Values are in cents (e.g.,
2500= €25.00)
Line Item and Modifier Quantities
Quantities and prices on a line item are per unit:
- A line item's
quantityis the number of units ordered, and itsprice_amountis the price of one unit. - A modifier's
quantityis how many times it was selected on one unit of its parent, not the total across the line. Itsprice_amountis the price of one selection. - Nested
modifiersfollow the same rule, relative to the modifier they belong to.
So a line's total is its quantity × (price_amount + each modifier's quantity × price_amount). For example, two Cheeseburgers with Extra Cheese on each:
{
"line_items": [
{
"name": "Cheeseburger",
"quantity": 2,
"price_amount": 1200,
"price_currency": "usd",
"modifiers": [
{
"name": "Extra Cheese",
"quantity": 1,
"price_amount": 100,
"price_currency": "usd",
"modifiers": []
}
]
}
],
"subtotal": 2600
}
The line total is 2 × (1200 + 1 × 100) = 2600.
Do not read a modifier's quantity as the total for the line. If you treat Extra Cheese above as 1 slice shared across both burgers, the ticket and the price are both wrong. Apply the modifier to each unit. When you check a modifier against a group that allows each option only once per item, compare its quantity with that per-unit limit, not with the limit multiplied by the line quantity.
Order Markup Values
The default behavior for item markups is to submit the order into the POS at the price it was ordered on the DSP, inclusive of markup.
To receive order markup total as a distinct line item, please reach out to Partner API support to enable this for your integration. See POS Feature Flags.
Markup Line Item Example
If enabled, markup will be provided as a separate line item where the markup total across all items on the order is shown:
{
"line_items": [
{
"name": "Burger",
"quantity": 1,
"price_amount": 1200,
"price_currency": "usd",
"modifiers": []
},
{
"name": "Uber Markup",
"quantity": 1,
"price_amount": 250,
"price_currency": "usd",
"modifiers": []
}
]
}
In this example, the markup total is $2.50.
Order Discounts
When a promotion is configured on the ordering channel, we will attach this information to the order to allow for accurate reporting within the POS. The discounts array will contain details about the discounts applied to the order, but discount amounts are NOT subtracted from item level prices or order subtotal.
Discount information can be provided in two forms: order-level and item-level.
Order-Level Discounts
When you have an order-level discount, the items field will be omitted from the discount record:
{
"discounts": [
{
"provider_id": "discount_id",
"amount": 250
}
]
}
Item-Level Discounts
When you have an item-level discount, the items array will reference the applicable items for the discount:
{
"discounts": [
{
"provider_id": "discount_id",
"amount": 250,
"items": [
{
"provider_id": "variation_id"
}
]
}
]
}
When a single discount spans multiple items (for example a "buy one, get one" promotion across two different line items), each entry in items may include an optional amount (in cents, positive) giving that line's share of the discount:
{
"discounts": [
{
"provider_id": "bogo_id",
"amount": 500,
"items": [
{
"provider_id": "variation_id_1",
"amount": 300
},
{
"provider_id": "variation_id_2",
"amount": 200
}
]
}
]
}
When items[].amount is present, apply each item's amount to that specific line rather than distributing the discount's top-level amount yourself — the per-item amounts sum to the discount amount (300 + 200 = 500). When items[].amount is omitted, existing behavior is unchanged.
Cash Orders
When an order is paid in cash (unpaid: true), cash_amount_due is the amount the customer hands over at fulfillment. This value comes directly from the ordering platform and is not guaranteed to equal the order subtotal or total:
- It can be less than the total when the platform funds a promotion that reduces the cash owed without a separate discount line.
- It can be more than subtotal + delivery when the customer pays platform fees in cash. These are surfaced in
dsp_fees— for example an Uber marketplace fee or a Wolt small-order surcharge. They are collected in cash by the merchant on the platform's behalf (and typically recouped by the platform at payout), so they are not merchant revenue and are kept separate fromservice_charge.
When part of the order was already paid electronically (e.g. platform credits or card) and only the remainder is due in cash, that prepaid portion is provided in amount_paid_by_other_methods.
To reconcile the cash to collect against the order components:
cash_amount_due = subtotal
+ tax
+ delivery_fee
+ delivery_fee_taxes
+ service_charge
+ dsp_fees
- discounts
- amount_paid_by_other_methods
Example
An order with a €19.99 item and a €3.00 delivery fee also carries a €1.60 platform fee the customer pays in cash. Only the fee is surfaced in dsp_fees; the cash to collect is €24.59:
{
"subtotal": 1999,
"delivery_fee": 300,
"dsp_fees": 160,
"unpaid": true,
"cash_amount_due": 2459
}
Bundles
A bundle is a set of items sold together (for example, a combo meal). Stream sends bundles to the POS as their individual line items rather than a single bundled item, so an order's pricing and item totals are unaffected by bundling.
To let you identify which items in an order belong to a bundle — for reporting or other purposes — Stream surfaces bundle information on the order payload. This information is optional to consume; existing behavior for non-bundle orders is unchanged.
- Each line item that belongs to a bundle carries a
bundle_id. - The order-level
bundlesarray describes each bundle (id,name,quantity,price_amount). - A line item's
bundle_idreferences the matchingidin thebundlesarray. - When an order contains more than one bundle, each bundle has a distinct
id, so items can be attributed to the correct bundle. - Items that are not part of a bundle omit
bundle_id, and thebundlesarray is only present when the order contains at least one bundle.
In the example below, the first two items belong to the bundle_1 bundle and the third item is a regular, non-bundle item:
{
"line_items": [
{
"provider_id": "burger_id",
"name": "Burger",
"quantity": 1,
"price_amount": 800,
"price_currency": "usd",
"modifiers": [],
"bundle_id": "bundle_1"
},
{
"provider_id": "fries_id",
"name": "Fries",
"quantity": 1,
"price_amount": 400,
"price_currency": "usd",
"modifiers": [],
"bundle_id": "bundle_1"
},
{
"provider_id": "soda_id",
"name": "Soda",
"quantity": 1,
"price_amount": 200,
"price_currency": "usd",
"modifiers": []
}
],
"bundles": [
{
"id": "bundle_1",
"name": "Combo Meal",
"quantity": 1,
"price_amount": 1099
}
]
}