> ## 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.

# Create order (v2)

> Create an order in Fire from the POS, the kiosk, or an aggregator integrator, using the same order structure they already send today.

Creates an order in Fire. The **POS**, the **kiosk**, and **aggregator integrators** use it to send
their sales straight to Fire **without changing the body** they already build: only the URL, the
credential, and how you read the response change.

This is **version 2**: it takes the POS and kiosk order structure and the aggregator structure. If
your system already sends orders in Fire format, use [Create order (v1)](https://docs.fire.rest/en/api-reference/create-order.md).
Both versions are current and end up in the same place: same validations, same response.

Fire recognizes the kind of order from the body's `channel.uid`:

* If the channel belongs to an aggregator (iFood, 99Food, Keeta, Rappi), the body is the one from
  [Inject order](https://docs.fire.rest/en/api-reference/orders.md) (camelCase, with prices and totals).
* Any other channel (POS, kiosk) uses the POS and kiosk structure described below (snake\_case,
  unit price only: Fire calculates the totals).

Once created, the order follows the same lifecycle as any Fire order: taxes, business day, fiscal
document, and [events](https://docs.fire.rest/en/events/overview.md).

## Authentication

**x-api-key** `string` *required*

Your Fire API key with the `orders:write` scope. `Authorization: Bearer <api_key>` is also accepted.
The key **must be bound to a vendor**: the order's account comes from that vendor. A key without a
vendor is rejected with `403`. You don't need to send the `account` header; if it arrives, it is ignored.

## Customer identity (POS and kiosk)

Send **exactly one** of these two headers. If you send neither, or both, the order is rejected with
`400` `VALIDATION_ERROR`. Aggregator orders don't use them.

**anonymous\_customer\_uid** `string`

Identifier of the device's anonymous session (POS or kiosk). This is the usual case.

**customer\_uid** `string`

Identifier of a registered customer.

## Body — POS and kiosk

**order\_code** `string` *required*

Unique order code in your system. If an order with that code already exists for your vendor,
the response is `409`.

**vendor\_uid** `string` *required*

Order vendor (e.g. `11.6.1350`).

**catalog\_uid** `string` *required*

Catalog of the sales channel.

**status** `string`

`COMPLETED` if the sale is closed; `OPEN` if it is still waiting to be charged. An order that does
not arrive as `COMPLETED` + `SUCCEEDED` stays pending payment.

**payment\_status** `string`

`SUCCEEDED` if it has already been charged.

**channel** `object` *required*

Sales channel. Its `uid` decides how the body is read.

**channel**

**uid** `string` *required*

Channel UID in Fire.

**code** `string` *required*

Channel code (e.g. `POS`, `KIOSK`).

**service** `object` *required*

Sale service.

**service**

**uid** `string` *required*

Service UID in Fire.

**code** `string` *required*

Service code (e.g. `Dine-In`, `Takeaway`).

**store** `object` *required*

Store of the sale.

**store**

**uid** `string` *required*

Store UID.

**code** `string` *required*

Store code.

**name** `string` *required*

Store name.

**vendor\_uid** `string` *required*

Store vendor.

**vendor\_name** `string` *required*

Vendor name.

**fulfillment** `object` *required*

Delivery method and catalog.

**fulfillment**

**method** `string` *required*

`POS` or `KIOSK`.

**catalog\_uid** `string` *required*

Catalog. It must be enabled for your account.

**details** `object`

Delivery data, e.g. `buzzer_name` (name used to call the customer).

**device** `object`

Device that recorded the sale: `uid`, `name`, `metadata`.

**operator** `object`

Cashier or operator: `uid`, `name`, `session` (`uid`, `start_timestamp`, `end_timestamp`).
`null` on the kiosk.

**customer** `object`

Customer data: `uid`, `name`, `last_name`, `phone` (required if you send the object), `email`,
`gov_id_type`, `gov_id_number`.

**billing** `object`

Billing data: `gov_id_type`, `gov_id_number`, `business_name`.

**metadata** `object`

Additional sale data, e.g. `display_code` (number used to call the order) and kiosk or POS data.

**order\_lines** `object[]` *required*

Order products.

**order\_lines\[]**

**hash** `string` *required*

Line identifier within the order.

**item\_id** `string` *required*

Product UID in the catalog.

**item\_description** `string` *required*

Product name.

**item\_type** `string` *required*

Item type (e.g. `PRODUCT`).

**quantity** `string` *required*

Quantity, as text (`"1"`).

**selected\_currency** `string` *required*

Currency (e.g. `BRL`).

**vendor\_uid** `string` *required*

Vendor.

**store\_uid** `string` *required*

Store.

**fulfillment** `object` *required*

`method` and `catalog_uid`, as in the order.

**price** `object` *required*

Unit price only: `unit_price[]` with `currency_code`, `gross_price`, `net_price`, `taxes`,
`taxes_value`, `discount_value`, `subtotal_before_taxes`, and `discounts`. Amounts are sent as
text (`"14.9"`). Fire calculates the line and order totals.

**modifier\_groups** `object[]` *required*

Modifier groups (`uid`, `description`, `selected_modifiers[]`). Each modifier has the same shape
as a line. `[]` if there are none.

**additional\_info** `object`

Product codes, e.g. `code`, `external_code`, `ncm`.

**payment\_methods** `object[]` *required*

Order payments.

**payment\_methods\[]**

**uid** `string` *required*

Payment method UID.

**method** `string` *required*

Payment method (e.g. `CASH`, `CREDIT`, `DEBIT`).

**currency\_code** `string` *required*

Currency.

**total** `string` *required*

Amount paid, as text.

**details** `object`

Transaction details: `processor`, `transaction_status` (`APPROVED`, `PENDING`),
`transaction_type`, `transaction_id`, `tid`, `authorization_code`, `total_bill`,
`customer_cash_amount`, `change_amount`, `card`, `acquirer`, `transaction_date`. A `PENDING`
payment leaves the order open, waiting to be charged.

**metadata** `object`

Payment authorizer data.

## Body — aggregators

The same body as [Inject order](https://docs.fire.rest/en/api-reference/orders.md), unchanged. Fire identifies it as an
aggregator order by `channel.uid` and records it as closed and paid.

## Response

**success** `boolean`

`true` when the order was created.

**data** `object`

**data**

**id** `string`

Order ID in Fire. Use it to read, update, or cancel the order.

**external\_order\_id** `string`

The `order_code` you sent.

**status** `string`

`COMPLETED` or `OPEN`.

**payment\_status** `string`

`SUCCEEDED` or `PENDING`.

**business\_day\_date** `string`

Store business day, `YYYY-MM-DD`.

**created\_at** `string`

Creation date in Fire (ISO 8601).

## Errors

| HTTP | `error` / `code` | When |
| - | - | - |
| `400` | `VALIDATION_ERROR` | The order code is missing, the body can't be read (POS/kiosk: `details[]` details each problem; aggregators: the message says what is missing), the customer headers are missing or both were sent, or the channel is not enabled for your vendor |
| `400` | `BUSINESS_ERROR` | Store inactive, business day closed, or the order breaks a validation rule enabled for your vendor (`ORDER_INVARIANT_VIOLATION`) |
| `404` | `NOT_FOUND` | The store doesn't exist |
| `401` | `UNAUTHORIZED` | Invalid, expired, or revoked API key |
| `403` | `FORBIDDEN` | API key without the `orders:write` scope or not bound to a vendor |
| `409` | `CONFLICT` / `DUPLICATE_ORDER` | The order already existed for your vendor. `data` carries the existing order's `id`, `externalOrderId`, and `status` |

> [!NOTE]
>
> Every request is recorded in Fire with its body and the rejection reason, including rejected
> ones. If you retry an order that was already created, the response is `409` and it isn't duplicated.

```bash POS or kiosk theme={null}
curl -X POST https://app.fire.rest/api/v2/external/orders \
  -H "x-api-key: $FIRE_API_KEY" \
  -H "anonymous_customer_uid: device-session-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "order_code": "BR-K000-05-1793063248",
    "vendor_uid": "11.6.1350",
    "catalog_uid": "5",
    "status": "COMPLETED",
    "payment_status": "SUCCEEDED",
    "channel": { "uid": "c784d4ba-23c7-4929-b2f0-1a1960d9cdc2", "code": "KIOSK" },
    "service": { "uid": "726c4892-48b9-45da-b066-2a8e83d2cb78", "code": "Dine-In" },
    "store": { "uid": "11.6.1350.50", "code": "K000", "name": "Tienda demo", "vendor_uid": "11.6.1350", "vendor_name": "Vendor demo" },
    "fulfillment": { "method": "KIOSK", "catalog_uid": "5", "details": { "buzzer_name": "Cliente" } },
    "customer": { "uid": "device-session-0001", "name": "CONSUMIDOR", "last_name": "FINAL", "phone": "" },
    "metadata": { "display_code": "48K" },
    "order_lines": [{
      "hash": "hash_0",
      "item_id": "7abdd4e5-d685-43ff-ba79-5e8b2f700b5b",
      "item_description": "12 Tiras de Frango",
      "item_type": "PRODUCT",
      "quantity": "1",
      "selected_currency": "BRL",
      "vendor_uid": "11.6.1350",
      "store_uid": "11.6.1350.50",
      "fulfillment": { "method": "KIOSK", "catalog_uid": "5" },
      "price": { "unit_price": [{ "currency_code": "BRL", "gross_price": "64.9", "net_price": "64.9", "taxes": [], "taxes_value": "0", "discount_value": "0", "subtotal_before_taxes": "64.9", "discounts": [] }] },
      "modifier_groups": []
    }],
    "payment_methods": [{
      "uid": "80242d0c-3bdd-4e8a-8ec2-eb250230b4e9",
      "method": "CREDIT",
      "currency_code": "BRL",
      "total": "64.9",
      "details": { "processor": "Tarjeta", "transaction_status": "APPROVED", "transaction_type": "CREDIT", "transaction_id": "BR-K000-05-1793063248", "tid": "TF000000", "authorization_code": "0000000000000", "total_bill": "64.9", "currency_code": "BRL", "exact_payment": false, "customer_cash_amount": "0", "mid": "", "voucher": "", "reference_number": "", "card": null, "acquirer": null, "transaction_date": { "date": "2026-10-26T22:08:00-03:00", "time_zone_name": "America/Sao_Paulo", "time_zone_type": "3" } }
    }]
  }'
```

```bash Aggregator theme={null}
curl -X POST https://app.fire.rest/api/v2/external/orders \
  -H "x-api-key: $FIRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @ifood-order.json   # same body as in "Inject order"
```

```json 201 theme={null}
{
  "success": true,
  "data": {
    "id": "6f1c2b9e-3a1d-4c55-9b7e-0d2f6a7c8e10",
    "external_order_id": "BR-K000-05-1793063248",
    "status": "COMPLETED",
    "payment_status": "SUCCEEDED",
    "business_day_date": "2026-10-26",
    "created_at": "2026-10-27T01:08:00.405Z"
  }
}
```

```json 409 theme={null}
{
  "success": false,
  "error": "CONFLICT",
  "code": "DUPLICATE_ORDER",
  "message": "Order with external id BR-K000-05-1793063248 already exists for this vendor.",
  "data": { "id": "6f1c2b9e-3a1d-4c55-9b7e-0d2f6a7c8e10", "externalOrderId": "BR-K000-05-1793063248", "status": "COMPLETED" }
}
```

```json 400 theme={null}
{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Datos de entrada inválidos",
  "details": [{ "code": "custom", "path": [], "message": "customer_uid or anonymous_customer_uid is required" }]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.