> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fire.rest/llms.txt
> Use this file to discover all available pages before exploring further.
# Inject order
> Inject an order into Fire. Fire manages the order lifecycle and sends status updates back via webhooks.
Bearer token obtained from [POST /login](/en/api-reference/login). Format: `Bearer `.
Your Fire API key.
Must be `integration`. Identifies the request as coming from an external integration.
Account identifier the request belongs to.
Unique order identifier from your system.
Order origin. Examples: `App`, `Kiosco`.
Client platform. Examples: `Android`, `iOS`, `Web`.
Sales channel details. Use `uid` values from publication webhook payloads (for example [`channel.updated`](/en/webhook-reference/channel-updated)) or from your channel setup in the Fire dashboard ([Aggregator integrations](/en/configuration/backoffice-integrations)).
Channel UID from Fire.
Channel type code. One of: `POS`, `Kiosk`, `App`, `Web`, `CallCenter`, `Aggregator`.
Additional channel metadata.
Fulfillment service details. Use `uid` values from the `services` array in those channel payloads or from the same sources as `channel`.
Service UID from Fire.
Fulfillment type code. One of: `DELIVERY`, `TAKEAWAY`, `PICKUP`, `DINE_IN`.
Additional service metadata.
Device details. `null` for channels without a physical device.
Device UID.
Device display name (e.g. `KIOSK`).
Device platform (e.g. `android`, `ios`).
Additional device metadata.
Fiscal point of emission of the device. Only used when
[requesting the fiscal document](/en/api-reference/fiscal-documents); here it is accepted and ignored.
Result of [Request fiscal document](/en/api-reference/fiscal-documents), copied as is.
Optional: if you did not fiscalize before injecting, omit it — Fire handles fiscalization on
its own.
Fire takes the receipt data for the order from here and ignores the rest. The document's
status before the tax authority is Fire's job: `documentStatus` is ignored if sent.
Operator or cashier who processed the order. `null` for self-service channels.
Operator UID.
Operator display name.
Active session details.
Session UID.
Additional operator metadata.
Shipping method selected by the customer. Values: `delivery`, `pickup`.
Whether the customer is accumulating loyalty points on this order.
Whether the customer is redeeming loyalty points on this order.
Whether discounts are applied on this order.
General comment from the customer for the entire order.
Customer information.
Customer's unique identifier from the authentication provider.
First name.
Last name.
Phone number.
Email address.
Government ID type. Example: `DNI`, `CI`.
Government ID number.
Customer ID in an external system.
Customer ID in Fire.
Billing details.
Business or person name for the invoice.
Government ID type for billing.
Government ID number for billing.
Billing phone number.
Billing email.
Billing address.
Billing ID in an external system.
Billing ID in Fire.
Extra customer data (e.g. birthdate, gender).
Store where the order is placed.
Store ID.
Store display name.
Store code.
Brand identifier.
Brand name.
Store latitude.
Store longitude.
Order contents.
Ordered products.
Product identifier.
Product display name.
Item type. Accepted values: `COMBO` (product with non-empty modifier groups), `PRODUCT` (simple sellable product), `MODIFIER` (pure modifier option — use in `selectedModifiers[]`), `PACKAGING` (packing-cost item). No default — omitting this field makes the payload invalid.
Quantity ordered.
Optional. Customer comment for this product line.
Reward or coupon applied to this product.
Pricing breakdown for this line item. Modifier lines use the same shape under `modifierGroups[n].selectedModifiers[n].price`.
Amounts for **one unit** (before multiplying by `quantity`).
ISO 4217 currency code (e.g. `BRL`, `USD`).
Optional. Price before any promotional pricing.
Subtotal excluding taxes. JSON may send this as a number or a string.
Discount percentage applied.
Discount amount.
Subtotal after discounts, before taxes.
Overall tax percentage for the band.
Tax amount for the band.
Final total for the band.
Suggested list price.
Per-tax breakdown (e.g. `IVA`, or Brazil ICMS, PIS, COFINS). Entries may omit `metadata` when not applicable.
Tax code or label (e.g. `IVA`, `icms`, `pis`, `cofins`).
Rate for this tax line (often a decimal string such as `0.00`).
Tax amount attributed to this line.
Optional region-specific fields (e.g. `cst` for ICMS).
Same keys as `unitPrice`. Represents the **full line** (typically unit values scaled by `quantity`). Include the same `taxes[]` shape when the API returns line-level tax detail.
Selected modifier groups.
Modifier group ID.
Modifier group description.
Chosen modifier options.
Answer/option ID.
Product used as this modifier option.
Modifier option name.
Item type. Accepted values: `COMBO` (product with non-empty modifier groups), `PRODUCT` (sellable product used as a modifier option), `MODIFIER` (pure modifier option), `PACKAGING` (packing-cost item). No default — omitting this field makes the payload invalid.
Added quantity.
Removed quantity (for ingredient removal).
Reward applied to this modifier.
Modifier pricing. Same structure as product price.
Nested modifier groups (up to 3 levels).
Additional data from the menu's `additionalInfo` field. Pass the value as received in the menu webhook payload.
Additional data from the menu's `additionalInfo` field. Pass the value as received in the menu webhook payload.
Shipping details depending on `selectedShippingMethod`.
Delivery details. Present when `selectedShippingMethod` is `delivery`.
Estimated delivery date/time.
Delivery address latitude.
Delivery address longitude.
Country.
City.
Main street address.
Street number.
Cross street or secondary address.
Delivery reference or landmark.
Property type ID.
Delivery instructions.
Contact number at delivery address.
ZIP or postal code.
Address nickname (e.g. "home", "office").
Address ID in external system.
Address ID in Fire.
ISO 8601 timestamp when driver arrived at store.
Extra delivery data.
Optional. Confirmation code used to verify delivery at the door.
Pickup details. Present when `selectedShippingMethod` is `pickup`.
Scheduled pickup date/time.
Preparation start date/time.
Preparation time unit. Example: `minute`.
Preparation time value.
Property type ID.
Carry-out option label.
Contact methods for pickup notification.
Contact type: `pager`, `sms`, `whatsapp`.
Identifier (for pager).
Phone country code.
Phone number.
Payment breakdown.
Order totals with tax and discount breakdown. Each entry is a price object with `currencyCode`, `subtotalWithoutTaxes`, `discountPercentage`, `discountsValue`, `subtotalIncludeDiscounts`, `taxesPercentage`, `taxValue`, `total`, and optionally `rewardId`.
Shipping fee lines. Each entry uses the **same price-band shape** as `totals[]`—send the fee already calculated (base, tax, and `total`). Fire stores the values as sent and exposes them as a shipping line downstream. See [Shipping and discounts](#shipping-and-discounts).
ISO 4217 currency code.
Amount before taxes.
Discount percentage applied to this line.
Discount amount.
Subtotal after discounts, before taxes.
Tax percentage applied.
Tax amount.
Line total including taxes.
Additional charges such as tips or packing costs.
Item type. Accepted values: `COMBO` (product with non-empty modifier groups), `PRODUCT` (simple sellable product), `MODIFIER` (pure modifier option), `PACKAGING` (packing-cost item). Typically `PACKAGING` for items in this array. No default — omitting this field makes the payload invalid.
Quantity.
Associated product ID, if any.
Charge description (e.g. `tip`, `packing cost`).
Currency code.
Amount before taxes.
Tax amount.
Total including taxes.
Order-level discount rows for promos or coupons applied **against the store's revenue** (the store absorbs the cost). Each entry uses the **same price-band fields** as `totals[]` and `shippingCost[]`. `discountsValue` is the amount deducted. **Leave this empty for aggregator platform discounts** — those are modeled as a `paymentMethods[]` entry instead. See [Aggregator discounts](#aggregator-discounts).
ISO 4217 currency code.
Taxable base before discount.
Discount percentage for this line.
Discount amount deducted.
Subtotal after discount, before taxes.
Tax percentage applied after discount.
Tax amount.
Line total including taxes.
Tax summary entries.
Tax name (e.g. `IVA 15%`).
Currency code.
Taxable base amount.
Tax percentage.
Total tax amount.
Payment methods used.
Payment processor name (e.g. `Kushki`, `Efectivo`).
Currency code.
Payment method code. Use `AGGREGATOR_DISCOUNT` when the aggregator platform covers a promotional discount and reimburses the store — this is always paired with `transactionType: "BENEFIT"`. See [Aggregator discounts](#aggregator-discounts).
Transaction type. Common values: `ONLINE`, `CREDIT`, `CASH`. Use `BENEFIT` when `paymentMethodCode` is `AGGREGATOR_DISCOUNT`.
Transaction identifier.
Transaction status (e.g. `APPROVED`).
Whether exact payment was provided.
Amount charged with this method.
Authorization number for NFCE (SiTef code 952 / IdAuth). Optional.
Customer receipt copy: printed receipt text for the cardholder (SiTef code 121 / ReceiptCustomer). Optional.
Merchant receipt copy: printed receipt text for the store (SiTef code 122 / ReceiptMerchant). Optional.
Acquiring bank details. Send `null` for payment methods without an acquirer.
Acquirer code.
Acquirer name.
Acquirer CNPJ for NFCE (SiTef code 950 / CNPJAuth). Optional.
Card details. Send `null` for non-card payment methods (e.g. `AGGREGATOR_DISCOUNT`).
Card brand (e.g. `VISA`, `MASTERCARD`, `AMEX`).
First 6 digits of the card number (BIN).
Masked card number.
Last 4 digits of the card number.
Cardholder name.
Country where the card was issued.
Processor-specific card brand identifier.
Card read method (SiTef code 2090 / Media). Accepted values: `CHIP`, `MAGNETIC`, `NFC`, `MANUAL`. Optional.
Transaction date with timezone info.
Processor-specific metadata.
Loyalty and coupon information.
Loyalty points accumulation and redemption breakdown.
Points earned: `storeCost`, `marketingCost`, `totalPoints`.
Points redeemed: `storeCost`, `marketingCost`, `totalPoints`.
Customer's current point balance.
Coupons and rewards applied.
Reward identifier.
Reward display name.
Extra reward data.
Extra order-level metadata (e.g. kiosk IP address).
## Amounts and price bands
Fire does **not** scale or recalculate prices. Send amounts in the **final currency unit** (for example `"8.99"` for USD 8.99, not cents). Your POS or aggregator must send values already calculated.
Product lines, `payments.totals[]`, `payments.shippingCost[]`, and `payments.discounts[]` all use the same **price band** keys: `currencyCode`, `subtotalWithoutTaxes`, `discountPercentage`, `discountsValue`, `subtotalIncludeDiscounts`, `taxesPercentage`, `taxValue`, `total`.
| Band field | Typical meaning |
| -------------------------- | ------------------------------------- |
| `subtotalWithoutTaxes` | Taxable base before the line discount |
| `discountsValue` | Discount amount on this line |
| `subtotalIncludeDiscounts` | Base after discount, before tax |
| `taxValue` | Tax on the discounted base |
| `total` | Line total stored as sent |
## Shipping and discounts
### Product-line discounts
Apply discounts on `order.products[n].price.unitPrice` and `totalPrice` (same numbers when `quantity` is 1). Example: **10% off** a **15.00** base with **12% VAT** → `discountsValue` **1.50**, `subtotalIncludeDiscounts` **13.50**, `taxValue` **1.62**, line `total` **15.12**.
### `payments.shippingCost[]`
Delivery or shipping fees as one or more price-band rows. In the examples below, shipping tax is calculated on the shipping base the same way as on products.
### `payments.discounts[]`
Order-level discounts (promos, coupons) as price-band rows. Use this when the discount is **not** already fully reflected in each product's `discountsValue` and the cost is **absorbed by the store**. Product discounts and `payments.discounts[]` can be combined; reconcile against `paymentMethods[].totalBill`.
### `payments.totals[]`
Roll-up of the **product** portion of the order. When reconciling: **products (totals) + shipping − order discounts ≈ amount paid**.
Fire does not reject the request if `paymentMethods[].totalBill` differs slightly from the sum of bands—still send consistent values from your source system.
## Combo discounts
When a combo product has a **container price of 0** (i.e. `type: "COMBO"` with `subtotalWithoutTaxes: 0`), the combo discount **must not** be placed on the container line. Assigning `discountsValue` to a zero-base produces negative totals, which Fire rejects.
Instead, **distribute the full discount amount across the `selectedModifiers`** that make up the combo.
### Rules
| Rule | Detail |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| COMBO container (`price === 0`) | All price fields must be `0` — no `discountsValue`, no negative values |
| Discount placement | Spread `discountsValue` across the modifiers proportionally to their base price |
| Non-negative constraint | After applying the discount, every modifier must have `subtotalIncludeDiscounts >= 0` and `total >= 0` |
| Totals reconciliation | `SUM(modifier.totalPrice.discountsValue)` must equal the combo's total discount, and sums must match `payments.totals[]` |
### Distribution algorithm
```
D = total combo discount
B = SUM(modifier.price.totalPrice.subtotalWithoutTaxes)
discount_i = ROUND(D × (base_i / B), 2)
net_i = base_i − discount_i // must be >= 0
```
Adjust rounding on the last modifier so that `SUM(discount_i) === D` exactly. If proportional distribution would leave any modifier with `net_i < 0`, cap that modifier's discount at its base price (`discount_i = base_i`, net = 0) and redistribute the remainder among the others.
### Example — BRL 17.94 discount on a combo (base BRL 89.68)
The following shows the **incorrect** pattern (discount placed on the container) and the **correct** pattern (discount spread across modifiers).
```json Incorrect — discount on zero-base COMBO (totals go negative) theme={null}
{
"type": "COMBO",
"price": {
"unitPrice": {
"subtotalWithoutTaxes": "0",
"discountsValue": "17.94",
"subtotalIncludeDiscounts": "-17.94",
"total": "-17.94"
}
}
}
```
```json Correct — COMBO container at zero, discount on modifiers theme={null}
{
"type": "COMBO",
"price": {
"unitPrice": { "subtotalWithoutTaxes": "0", "discountsValue": "0", "subtotalIncludeDiscounts": "0", "total": "0" },
"totalPrice": { "subtotalWithoutTaxes": "0", "discountsValue": "0", "subtotalIncludeDiscounts": "0", "total": "0" }
},
"modifierGroups": [
{
"selectedModifiers": [
{
"product": "12 Coxinhas da Asa",
"type": "MODIFIER",
"price": {
"unitPrice": { "subtotalWithoutTaxes": "22.30", "discountsValue": "4.46", "subtotalIncludeDiscounts": "17.84", "total": "17.84" },
"totalPrice": { "subtotalWithoutTaxes": "22.30", "discountsValue": "4.46", "subtotalIncludeDiscounts": "17.84", "total": "17.84" }
}
},
{
"product": "Batata Média",
"type": "MODIFIER",
"price": {
"unitPrice": { "subtotalWithoutTaxes": "4.59", "discountsValue": "0.92", "subtotalIncludeDiscounts": "3.67", "total": "3.67" },
"totalPrice": { "subtotalWithoutTaxes": "4.59", "discountsValue": "0.92", "subtotalIncludeDiscounts": "3.67", "total": "3.67" }
}
}
]
}
]
}
```
The full discount breakdown for this example (all 7 modifiers):
| Modifier | Base | `discountsValue` | Net |
| ------------------- | --------: | ---------------: | --------: |
| 12 Coxinhas da Asa | 22.30 | 4.46 | 17.84 |
| Batata Média | 4.59 | 0.92 | 3.67 |
| Onion Rings | 7.50 | 1.50 | 6.00 |
| Batata Grande | 6.50 | 1.30 | 5.20 |
| Molho Secreto 120g | 4.09 | 0.82 | 3.27 |
| Água sem Gás (×2) | 29.80 | 5.96 | 23.84 |
| Água com gás | 14.90 | 2.98 | 11.92 |
| **COMBO container** | **0** | **0** | **0** |
| **Total** | **89.68** | **17.94** | **71.74** |
`payments.totals[0].subtotalWithoutTaxes` = **89.68**, `subtotalIncludeDiscounts` = **71.74** ✓
## Aggregator discounts
When an aggregator platform (iFood, Rappi, UberEats, etc.) applies a promotional discount to the customer, the **aggregator reimburses the store** for that amount — the store always receives the full price. This means the discount is not a deduction from the store's revenue and must **not** appear in `payments.discounts[]`.
Model it instead as an extra entry in `payments.paymentMethods[]`:
| Who pays | What | How to model |
| ------------------ | --------------------------------------------------------- | ----------------------------------------------------------------------- |
| Customer | Products + shipping + extra charges − aggregator discount | `paymentMethods[n]` with the real payment code (`CREDIT`, `CASH`, etc.) |
| Aggregator | Discount amount (reimbursement to store) | `paymentMethods[n]` with `paymentMethodCode: "AGGREGATOR_DISCOUNT"` |
| **Store receives** | **Full products + shipping + extra charges** | — |
### Required fields on the `AGGREGATOR_DISCOUNT` entry
| Field | Value |
| ------------------- | ------------------------------------------------------- |
| `paymentMethodCode` | `"AGGREGATOR_DISCOUNT"` — same code for all aggregators |
| `processor` | Aggregator name: `"IFOOD"`, `"RAPPI"`, `"UBEREATS"`, … |
| `transactionType` | `"BENEFIT"` |
| `transactionStatus` | `"APPROVED"` |
| `card` | `null` |
| `totalBill` | Discount amount |
### Balance rule
The sum of **all** `paymentMethods[].totalBill` entries — including the `AGGREGATOR_DISCOUNT` entry — must equal the gross order total:
```
SUM(paymentMethods[].totalBill)
= SUM(order.products[].price.totalPrice.total)
+ SUM(payments.extraCharges[].total)
+ SUM(payments.shippingCost[].total)
```
`payments.discounts[]` stays **empty**.
```json Simple delivery (no discounts) theme={null}
{
"orderId": "AGG-SIMPLE-001",
"source": "App",
"platform": "Android",
"channel": { "uid": "CH-IFOOD-001", "code": "Aggregator", "metadata": {} },
"service": { "uid": "3", "code": "DELIVERY", "metadata": {} },
"selectedShippingMethod": "delivery",
"client": { "name": "Jane", "lastName": "Doe", "phone": "+1555000111" },
"store": { "id": 10, "name": "Gran Santa Fe", "code": "T001", "vendorId": 8 },
"order": {
"products": [
{
"productId": "991117",
"product": "Classic Burger",
"type": "PRODUCT",
"quantity": 1,
"price": {
"unitPrice": {
"currencyCode": "USD",
"subtotalWithoutTaxes": "7.7826",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "7.7826",
"taxesPercentage": "15.0000",
"taxValue": "1.1739",
"total": "8.9900"
},
"totalPrice": {
"currencyCode": "USD",
"subtotalWithoutTaxes": "7.7826",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "7.7826",
"taxesPercentage": "15.0000",
"taxValue": "1.1739",
"total": "8.9900"
}
},
"additional_info": { "externalCode": "burger-classic-ext-001" }
}
]
},
"shippingMethod": {
"delivery": {
"city": "Guayaquil",
"mainStreet": "Av. Principal 123",
"zipCode": "090101",
"additional_info": {
"deliveryConfirmationCode": "4821"
}
}
},
"payments": {
"totals": [
{
"currencyCode": "USD",
"subtotalWithoutTaxes": "7.7826",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "7.7826",
"taxesPercentage": "15.0000",
"taxValue": "1.1739",
"total": "8.9900"
}
],
"shippingCost": [
{
"currencyCode": "USD",
"subtotalWithoutTaxes": "1.5000",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "1.5000",
"taxesPercentage": "15.0000",
"taxValue": "0.2250",
"total": "1.7250"
}
],
"discounts": [],
"paymentMethods": [
{
"processor": "Kushki",
"currencyCode": "USD",
"transactionStatus": "APPROVED",
"totalBill": "10.7150"
}
]
}
}
```
```json Line discount and shipping theme={null}
{
"orderId": "AGG-DISC-LINE-001",
"source": "Kiosco",
"platform": "Android",
"channel": { "uid": "CH-KIOSK-001", "code": "Kiosk", "metadata": {} },
"service": { "uid": "3", "code": "DELIVERY", "metadata": {} },
"selectedShippingMethod": "delivery",
"client": { "name": "Maria", "phone": "+5511999999999" },
"store": { "id": 20, "name": "Centro", "code": "T020", "vendorId": 16 },
"order": {
"products": [
{
"productId": "SKU-COMBO-001",
"product": "Combo Especial",
"type": "COMBO",
"quantity": 1,
"comment": "Sin cebolla",
"price": {
"unitPrice": {
"currencyCode": "BRL",
"subtotalWithoutTaxes": "15.00",
"discountPercentage": "10.0000",
"discountsValue": "1.50",
"subtotalIncludeDiscounts": "13.50",
"taxesPercentage": "12.0000",
"taxValue": "1.62",
"total": "15.12"
},
"totalPrice": {
"currencyCode": "BRL",
"subtotalWithoutTaxes": "15.00",
"discountPercentage": "10.0000",
"discountsValue": "1.50",
"subtotalIncludeDiscounts": "13.50",
"taxesPercentage": "12.0000",
"taxValue": "1.62",
"total": "15.12"
}
},
"modifierGroups": [
{
"id": "MG-SAUCE-001",
"description": "Sauce",
"selectedModifiers": [
{
"answerId": "ANS-BBQ-001",
"productId": "MOD-BBQ-001",
"product": "BBQ Sauce",
"type": "MODIFIER",
"quantity": 1,
"additional_info": { "externalCode": "sauce-bbq-ext-001" }
}
]
}
],
"additional_info": { "externalCode": "combo-especial-ext-001" }
}
]
},
"shippingMethod": {
"delivery": {
"city": "São Paulo",
"mainStreet": "Rua Exemplo 100",
"zipCode": "01310-100"
}
},
"payments": {
"totals": [
{
"currencyCode": "BRL",
"subtotalWithoutTaxes": "15.00",
"discountPercentage": "10.0000",
"discountsValue": "1.50",
"subtotalIncludeDiscounts": "13.50",
"taxesPercentage": "12.0000",
"taxValue": "1.62",
"total": "15.12"
}
],
"shippingCost": [
{
"currencyCode": "BRL",
"subtotalWithoutTaxes": "3.50",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "3.50",
"taxesPercentage": "12.0000",
"taxValue": "0.42",
"total": "3.92"
}
],
"discounts": [],
"paymentMethods": [
{
"processor": "CREDIT_CARD",
"currencyCode": "BRL",
"transactionStatus": "APPROVED",
"totalBill": "19.04"
}
]
}
}
```
```json Multi-product, shipping, and order discount theme={null}
{
"orderId": "AGG-PROMO-001",
"source": "Aggregator",
"channel": { "uid": "CH-AGG-001", "code": "Aggregator", "metadata": {} },
"service": { "uid": "3", "code": "DELIVERY", "metadata": {} },
"selectedShippingMethod": "delivery",
"client": { "name": "João", "lastName": "Silva", "phone": "+5511987654321" },
"store": { "id": 30, "name": "Lab Brasil", "code": "K000", "vendorId": 8 },
"order": {
"products": [
{
"productId": "BURG-001",
"product": "Hamburguesa Clásica",
"type": "PRODUCT",
"quantity": 2,
"price": {
"unitPrice": {
"currencyCode": "BRL",
"subtotalWithoutTaxes": "11.52",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "11.52",
"taxesPercentage": "12.0000",
"taxValue": "1.38",
"total": "12.90"
},
"totalPrice": {
"currencyCode": "BRL",
"subtotalWithoutTaxes": "23.04",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "23.04",
"taxesPercentage": "12.0000",
"taxValue": "2.76",
"total": "25.80"
}
},
"additional_info": { "externalCode": "hamburguesa-clasica-ext-001" }
},
{
"productId": "BEV-001",
"product": "Refresco 500ml",
"type": "PRODUCT",
"quantity": 1,
"price": {
"unitPrice": {
"currencyCode": "BRL",
"subtotalWithoutTaxes": "4.46",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "4.46",
"taxesPercentage": "12.0000",
"taxValue": "0.54",
"total": "5.00"
},
"totalPrice": {
"currencyCode": "BRL",
"subtotalWithoutTaxes": "4.46",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "4.46",
"taxesPercentage": "12.0000",
"taxValue": "0.54",
"total": "5.00"
}
},
"additional_info": { "externalCode": "refresco-500ml-ext-001" }
}
]
},
"shippingMethod": {
"delivery": { "city": "São Paulo", "mainStreet": "Av. Paulista 1000" }
},
"payments": {
"totals": [
{
"currencyCode": "BRL",
"subtotalWithoutTaxes": "27.50",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "27.50",
"taxesPercentage": "12.0000",
"taxValue": "3.30",
"total": "30.80"
}
],
"shippingCost": [
{
"currencyCode": "BRL",
"subtotalWithoutTaxes": "3.50",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "3.50",
"taxesPercentage": "0.0000",
"taxValue": "0.0000",
"total": "3.50"
}
],
"discounts": [
{
"currencyCode": "BRL",
"subtotalWithoutTaxes": "34.30",
"discountPercentage": "0.0000",
"discountsValue": "2.00",
"subtotalIncludeDiscounts": "32.30",
"taxesPercentage": "0.0000",
"taxValue": "0.0000",
"total": "2.00"
}
],
"paymentMethods": [
{
"processor": "99",
"currencyCode": "BRL",
"transactionStatus": "APPROVED",
"totalBill": "32.30"
}
]
}
}
```
```json Aggregator discount (iFood reimburses BRL 1.00) theme={null}
{
"orderId": "AGG-DISC-IFOOD-001",
"source": "Aggregator",
"channel": { "uid": "CH-IFOOD-001", "code": "Aggregator", "metadata": {} },
"service": { "uid": "3", "code": "DELIVERY", "metadata": {} },
"selectedShippingMethod": "delivery",
"client": { "name": "João", "lastName": "Silva", "phone": "+5511987654321" },
"store": { "id": 30, "name": "Lab Brasil", "code": "K000", "vendorId": 8 },
"order": {
"products": [
{
"productId": "PROD-TESTE-001",
"product": "PEDIDO DE TESTE Suc",
"type": "PRODUCT",
"quantity": 2,
"price": {
"unitPrice": {
"currencyCode": "BRL",
"subtotalWithoutTaxes": "14.90",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "14.90",
"taxesPercentage": "0.0000",
"taxValue": "0.0000",
"total": "14.90"
},
"totalPrice": {
"currencyCode": "BRL",
"subtotalWithoutTaxes": "29.80",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "29.80",
"taxesPercentage": "0.0000",
"taxValue": "0.0000",
"total": "29.80"
}
},
"additional_info": { "externalCode": "pedido-teste-ext-001" }
}
]
},
"shippingMethod": {
"delivery": { "city": "São Paulo", "mainStreet": "Av. Paulista 1000", "zipCode": "01310-100" }
},
"payments": {
"totals": [
{
"currencyCode": "BRL",
"subtotalWithoutTaxes": "29.80",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "29.80",
"taxesPercentage": "0.0000",
"taxValue": "0.0000",
"total": "29.80"
}
],
"shippingCost": [
{
"currencyCode": "BRL",
"subtotalWithoutTaxes": "8.90",
"discountPercentage": "0.0000",
"discountsValue": "0.0000",
"subtotalIncludeDiscounts": "8.90",
"taxesPercentage": "0.0000",
"taxValue": "0.0000",
"total": "8.90"
}
],
"extraCharges": [
{
"type": "PACKAGING",
"quantity": 1,
"description": "Taxa de serviço",
"currencyCode": "BRL",
"subtotalWithoutTaxes": "0.99",
"taxValue": "0.0000",
"total": "0.99"
}
],
"discounts": [],
"paymentMethods": [
{
"processor": "IFOOD",
"currencyCode": "BRL",
"paymentMethodCode": "CREDIT",
"transactionType": "ONLINE",
"transactionStatus": "APPROVED",
"exactPayment": true,
"totalBill": "38.69",
"id_auth": "123456",
"receipt_customer": "CUSTOMER RECEIPT\nAMEX ****1234\nAPPROVED",
"receipt_merchant": "MERCHANT RECEIPT\nAMEX ****1234\nAPPROVED",
"card": {
"brand": "AMEX",
"bin": "378282",
"mask": "3782 82****1234",
"lastFourDigits": "1234",
"holder": "JOAO SILVA",
"cardCountry": "BR",
"externalCardBrandId": "",
"media": "CHIP"
},
"acquirer": {
"code": "01",
"name": "CIELO",
"cnpj": "01.027.058/0001-91"
}
},
{
"processor": "IFOOD",
"currencyCode": "BRL",
"paymentMethodCode": "AGGREGATOR_DISCOUNT",
"transactionType": "BENEFIT",
"transactionId": "0ec06303-28f8-4d1f-aa3d-8b88aadb9814",
"transactionStatus": "APPROVED",
"exactPayment": true,
"totalBill": "1.00",
"card": null,
"acquirer": { "code": "", "name": "" }
}
]
}
}
```
## Example reconciliations
| Example | Products (`totals[].total`) | Shipping (`shippingCost[].total`) | Order discount (`discounts[].discountsValue`) | Paid (`totalBill`) |
| ------------------------ | --------------------------: | --------------------------------: | --------------------------------------------: | ---------------------------------------------------: |
| Simple delivery | 8.99 | 1.73 | — | **10.72** |
| Line discount + shipping | 15.12 | 3.92 | — | **19.04** |
| Multi-product + promo | 30.80 | 3.50 | 2.00 | **32.30** |
| Aggregator discount | 29.80 | 8.90 | — | **39.69** (CREDIT 38.69 + AGGREGATOR\_DISCOUNT 1.00) |
Calculation notes:
* **Simple delivery:** 8.99 + 1.73 = **10.72**.
* **Line discount:** 10% off 15.00 → tax on 13.50 → product **15.12**; shipping 3.50 + 12% VAT = **3.92**; **15.12 + 3.92 = 19.04**.
* **Multi-product + promo:** burgers **25.80** + drink **5.00** = **30.80**; + shipping **3.50** = 34.30; − promo **2.00** = **32.30** paid.
* **Aggregator discount:** products **29.80** + packaging **0.99** + shipping **8.90** = **39.69** gross; customer pays **38.69** (CREDIT) + aggregator reimburses **1.00** (AGGREGATOR\_DISCOUNT) = **39.69** ✓. `payments.discounts` is empty.
```json 200 theme={null}
{
"data": {
"uid": "92eb4720-dbee-4786-ad76-b0b01aa47f36",
"order_code": "99-2c6970fd-a164-48bd-9f45-d5098a679a8f",
"account_uid": "100",
"vendor_uid": "100.6.1350",
"store_uid": "100.6.1350.1",
"catalog_uid": "200a6bf1-55dd-4c9b-af2b-07a62cb0d6f2",
"channel": {
"uid": "200a6bf1-55dd-4c9b-af2b-07a62cb0d6f2",
"code": "KEETA",
"metadata": {
"partner": "99"
}
},
"service": {
"uid": "91c2c168-5a4b-4944-977e-75a1ea7a77e7",
"code": "DELIVERY",
"metadata": {}
},
"device": {
"uid": "99-aggregator-device",
"name": "99 Aggregator",
"metadata": {
"ip": "0.0.0.0"
}
},
"operator": {
"uid": "99-operator",
"name": "99",
"session": {
"uid": "sess-99-aggregator"
}
},
"store": {
"uid": "100.6.1350.1",
"code": "K000",
"name": "Laboratorio Brasil",
"latitude": "-23.5632",
"longitude": "-46.6543",
"vendor_uid": "100.6.1350",
"vendor_name": "Sandbox Brasil"
},
"anonymous_customer_uid": "99-client-e24b0c40-43ff-4d0e-b384-b1f3e1173193",
"customer_uid": null,
"customer": {
"uid": "99-client-e24b0c40-43ff-4d0e-b384-b1f3e1173193",
"name": "João",
"email": "joao.silva@email.com",
"phone": "11987654321",
"last_name": "Silva",
"gov_id_type": "CPF",
"gov_id_number": "123.456.789-09"
},
"billing_uid": null,
"billing": null,
"fulfillment": {
"method": "DELIVERY",
"details": {
"uid": "99-client-e24b0c40-43ff-4d0e-b384-b1f3e1173193",
"city": "São Paulo",
"country": "Brasil",
"latitude": "-23.5632",
"zip_code": "01310-100",
"longitude": "-46.6543",
"reference": "Apto 42",
"main_street": "Av. Paulista 1000",
"delivery_date": "2026-05-11T14:38:16.360Z"
},
"catalog_uid": "200a6bf1-55dd-4c9b-af2b-07a62cb0d6f2"
},
"status": "COMPLETED",
"payment_status": "SUCCEEDED",
"payment_methods": [
{
"uid": "6781726c-4dbb-4cb9-a8e6-a76a7283b102",
"total": "347800",
"method": "99",
"details": {
"mid": null,
"tid": null,
"card": {
"bin": "",
"mask": "",
"brand": "",
"holder": "",
"card_country": "",
"last_four_digits": "",
"external_card_brand_id": "CASH"
},
"voucher": null,
"acquirer": {
"code": "",
"name": ""
},
"metadata": {},
"processor": "99",
"total_bill": "347800",
"currency_code": "BRL",
"exact_payment": false,
"transaction_id": "99-txn-5d7faa7d-f1aa-4af2-9f57-614cf5346eb4",
"reference_number": null,
"transaction_date": {
"date": "2026-05-11T14:38:17.482Z",
"time_zone_name": "UTC",
"time_zone_type": "0"
},
"transaction_type": "cash",
"authorization_code": "",
"transaction_status": "APPROVED",
"customer_cash_amount": "0"
},
"metadata": {},
"currency_code": "BRL"
}
],
"metadata": {
"pos": {
"discount": false,
"order_id": "99-2c6970fd-a164-48bd-9f45-d5098a679a8f",
"account_id": "100",
"created_at": "2026-05-11T14:38:16.360Z",
"order_comment": ""
},
"additional_info": {}
},
"created_at": "2026-05-11 14:38:18.767989",
"updated_at": "2026-05-11 14:38:18.767989",
"deleted_at": null,
"order_lines": [
{
"uid": "2fe6b60a-50e0-40f3-8040-91a26f1888b5",
"hash": "001224591808cb3551c9d0c248b739ef07dd8dd3f958d3eb1251ca5f022bad48",
"price": {
"unit_price": [
{
"taxes": [
{
"name": "IVA",
"percentage": "0"
}
],
"metadata": {},
"discounts": [],
"net_price": "17.39",
"gross_price": "17.39",
"taxes_value": "0",
"currency_code": "BRL",
"discount_value": "0",
"subtotal_before_taxes": "17.39"
}
],
"total_price": [
{
"taxes": [
{
"name": "IVA",
"percentage": "0"
}
],
"metadata": {},
"discounts": [],
"net_price": "34.78",
"gross_price": "34.78",
"taxes_value": "0",
"currency_code": "BRL",
"discount_value": "0",
"subtotal_before_taxes": "34.78"
}
]
},
"item_id": "001224591808cb3551c9d0c248b739ef07dd8dd3f958d3eb1251ca5f022bad48",
"quantity": "2",
"item_type": "PRODUCT",
"store_uid": "100.6.1350.1",
"updated_at": "2026-05-11T14:38:17.481Z",
"vendor_uid": "100.6.1350",
"fulfillment": {
"method": "DELIVERY",
"catalog_uid": "200a6bf1-55dd-4c9b-af2b-07a62cb0d6f2"
},
"line_totals": [
{
"taxes": [
{
"name": "IVA",
"percentage": "0"
}
],
"total": "34.78",
"subtotal": "34.78",
"discounts": [],
"taxes_value": "0",
"currency_code": "BRL",
"discount_value": "0",
"subtotal_before_taxes": "34.78"
}
],
"modifier_groups": [],
"item_description": "X-Burguer",
"selected_currency": "BRL"
}
],
"totals": [
{
"taxes": [
{
"name": "IVA",
"percentage": "0"
}
],
"total": "34.78",
"subtotal": "34.78",
"discounts": [],
"taxes_value": "0",
"currency_code": "BRL",
"discount_value": "0",
"subtotal_before_taxes": "34.78"
}
]
},
"isArray": false,
"status": 200,
"method": "POST",
"pathname": "/stage/api/v4/aggregator/orders",
"duration": 4900,
"traceId": "1-6a01e9d9-7c9577787de4d07a2c14686b;Parent"
}
```
```json 400 theme={null}
{
"error": {
"code": "validation_error",
"message": "channelId is required"
}
}
```
```json 409 theme={null}
{
"error": {
"code": "duplicate_order",
"message": "An order with orderId '0000012194-081101' already exists"
}
}
```