> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plato.ae/llms.txt
> Use this file to discover all available pages before exploring further.

# Aggregator Integration

> Push delivery and pickup orders from an ordering aggregator into Plato POS and KDS.

The Aggregator Integration API lets an external ordering platform create restaurant orders and send order status updates to Plato.

Use it for marketplace, delivery, call-center, and first-party ordering systems that already collect the customer and cart before sending the order to the restaurant.

Customer information is optional. An order only needs customer details when the aggregator chooses to provide them. Delivery orders still require a delivery address.

## Integration Flow

1. Create a dedicated API key and role in Plato Console.
2. Give the role `restaurant:order:create` and `restaurant:order:changeStatus`.
3. Map your item identifiers to Plato products when a mapping is available.
4. Send each order to `POST /api/v1/aggregators/orders`.
5. Save the returned Plato order `id` and `referenceNumber`.
6. Send later status changes to the Order Update webhook.
7. Retry timeouts with the same `externalOrderId` and `Idempotency-Key`.

New orders enter Plato with `PENDING` status and are broadcast to connected POS and KDS devices.

<Note>
  This endpoint is for trusted server-to-server integrations. Never put the API
  key in a marketplace frontend, browser bundle, or mobile application.
</Note>

## Endpoints

| Endpoint                                  | Purpose                                 |
| ----------------------------------------- | --------------------------------------- |
| `POST /api/v1/aggregators/orders`         | Create an aggregator order.             |
| `POST /api/v1/aggregators/orders/updates` | Send an order status update into Plato. |

Use `https://api.plato.ae` as the production base URL or `http://localhost:2024` for local testing.

## Authentication

Send a dedicated Plato API key as a Bearer token:

```http theme={null}
Authorization: Bearer plato_your_api_key
```

The `x-api-key` header is also accepted. See [Authentication](/api-reference/authentication) for key safety guidance.

## Aggregator Identifiers

Send the aggregator's canonical Plato slug directly in the `type` field:

| Aggregator | Value        |
| ---------- | ------------ |
| Talabat    | `talabat`    |
| Noon Food  | `noon_food`  |
| Careem     | `careem_eat` |
| Deliveroo  | `deliveroo`  |
| Smiles     | `smiles`     |
| Keeta      | `keeta`      |
| Drivu      | `drivu`      |
| Beanz      | `beanz`      |

These canonical values make the aggregator name and icon appear as the order source in Plato POS and KDS. Plato also accepts `noon`, `noon-food`, or `noonfood` as aliases for `noon_food`, and `careem`, `careem-eat`, or `careem-eats` as aliases for `careem_eat`.

The selected aggregator app must already be installed in the API key's workspace. If it is not installed, Plato returns `409 AGGREGATOR_APP_NOT_INSTALLED` and does not create the order.

<Note>
  You only send `type: "talabat"`. Plato resolves it internally to `type:
      "PICK_UP"` and `appSlug: "talabat"`. Do not send `appSlug` in the request.
</Note>

## Order Identity

The pair of `type` and `externalOrderId` identifies an order.

For example:

```json theme={null}
{
  "type": "talabat",
  "externalOrderId": "TLB-84721"
}
```

Sending the same pair and payload again returns the original Plato order instead of creating a duplicate. An `Idempotency-Key` header provides a second retry guard and is strongly recommended.

## Product Mapping

Each item may include a `platoProductId`.

* When supplied, `platoProductId` is stored with the order item snapshot for correlation.
* When omitted, Plato stores the item as an aggregator product snapshot using its external id, SKU, name, and price.
* Item details are stored from the submitted payload; the endpoint does not fetch menu products.

Product mapping is recommended because it helps correlate the aggregator catalog with the Plato catalog.

## Money Rules

All money values are decimal major-unit amounts. For AED, send `25.50`, not `2550` fils.

Plato validates that:

* Every explicit item total equals `quantity × unitPrice`.
* `pricing.subtotal` equals the sum of all item totals.
* `pricing.total` matches subtotal, delivery fee, charges, discount, and VAT.

The allowed rounding difference is AED `0.05` or the equivalent amount in the selected currency.

Continue with [Create An Order](/api-reference/aggregators/create-order) for the complete payload.