Skip to main content
POST
/
api
/
v4
/
integrations
/
sales
/
aggregator
/
orders
{
  "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"
          }
        }
      }
    ]
  },
  "shippingMethod": {
    "delivery": {
      "city": "Guayaquil",
      "mainStreet": "Av. Principal 123",
      "zipCode": "090101",
      "additionalInfo": {
        "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"
      }
    ]
  }
}

{
  "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"
}
​
Authorization
string
required
Bearer token obtained from POST /login. Format: Bearer <accessToken>.
​
x-api-key
string
required
Your Fire API key.
​
x-client-channel
string
required
Must be integration. Identifies the request as coming from an external integration.
​
account
string
required
Account identifier the request belongs to.
​
orderId
string
required
Unique order identifier from your system.
​
source
string
required
Order origin. Examples: App, Kiosco.
​
platform
string
Client platform. Examples: Android, iOS, Web.
​
channel
object
required
Sales channel details. Use uid values from publication webhook payloads (for example channel.updated) or from your channel setup in the Fire dashboard (Aggregator integrations).
​
service
object
required
Fulfillment service details. Use uid values from the services array in those channel payloads or from the same sources as channel.
​
device
object
Device details. null for channels without a physical device.
​
operator
object
Operator or cashier who processed the order. null for self-service channels.
​
selectedShippingMethod
string
required
Shipping method selected by the customer. Values: delivery, pickup.
​
accumulatePoints
boolean
Whether the customer is accumulating loyalty points on this order.
​
redeemPoints
boolean
Whether the customer is redeeming loyalty points on this order.
​
discount
boolean
Whether discounts are applied on this order.
​
orderComment
string
General comment from the customer for the entire order.
​
client
object
required
Customer information.
​
store
object
required
Store where the order is placed.
​
order
object
required
Order contents.
​
shippingMethod
object
required
Shipping details depending on selectedShippingMethod.
​
payments
object
required
Payment breakdown.
​
marketing
object
Loyalty and coupon information.
​
additionalInfo
object
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 fieldTypical meaning
subtotalWithoutTaxesTaxable base before the line discount
discountsValueDiscount amount on this line
subtotalIncludeDiscountsBase after discount, before tax
taxValueTax on the discounted base
totalLine 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.

​
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 paysWhatHow to model
CustomerProducts + shipping + extra charges − aggregator discountpaymentMethods[n] with the real payment code (CREDIT, CASH, etc.)
AggregatorDiscount amount (reimbursement to store)paymentMethods[n] with paymentMethodCode: "AGGREGATOR_DISCOUNT"
Store receivesFull products + shipping + extra charges—

​
Required fields on the AGGREGATOR_DISCOUNT entry

FieldValue
paymentMethodCode"AGGREGATOR_DISCOUNT" — same code for all aggregators
processorAggregator name: "IFOOD", "RAPPI", "UBEREATS", …
transactionType"BENEFIT"
transactionStatus"APPROVED"
cardnull
totalBillDiscount 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. 
{
  "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"
          }
        }
      }
    ]
  },
  "shippingMethod": {
    "delivery": {
      "city": "Guayaquil",
      "mainStreet": "Av. Principal 123",
      "zipCode": "090101",
      "additionalInfo": {
        "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"
      }
    ]
  }
}

​
Example reconciliations

ExampleProducts (totals[].total)Shipping (shippingCost[].total)Order discount (discounts[].discountsValue)Paid (totalBill)
Simple delivery8.991.73—10.72
Line discount + shipping15.123.92—19.04
Multi-product + promo30.803.502.0032.30
Aggregator discount29.808.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.
{
  "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"
}