Search in documentation

Modules

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Solutions

Implementation guide — Order API

Implement the Order API step by step, from receiving orders through complete resolution.Prerequisites:

Understand the Fundamentals (order types, categories, SLA)
Have a valid authentication token
Choose your event consumption method (polling or webhook)

1. Receive new orders

Orders arrive as events. Choose your consumption method:

Polling (recommended to start)

Check every 30 seconds:

curl -X GET "https://merchant-api.ifood.com.br/order/v1.0/orders:polling" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200 OK):

{
  "events": [
    {
      "id": "evt_123",
      "code": "CONFIRMED",
      "fullCode": "ORDER_CONFIRMED",
      "orderId": "ord_456",
      "createdAt": "2024-04-25T18:00:00Z",
      "metadata": {
        "id": "ord_456",
        "status": "CONFIRMED",
        "category": "FOOD",
        "orderType": "DELIVERY",
        "items": [...]
      }
    }
  ]
}

Webhooks (scalable)

Configure your endpoint to receive events directly. iFood will send POST with same structure above.Implementation in JavaScript:

const express = require('express');
const app = express();

app.post('/webhooks/orders', express.json(), (req, res) => {
  const { events } = req.body;

  events.forEach(event => {
    if (event.code === 'CONFIRMED') {
      // Process new order
      console.log(`New order: ${event.metadata.id}`);
    }
  });

  // Acknowledge immediately
  res.status(200).json({ acknowledged: true });
});

app.listen(3000);

Next step: After receiving event, acknowledge reading with /acknowledgment.

2. Acknowledge event consumption

After processing events, confirm they were consumed:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders:acknowledgment" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "acknowledgedEventIds": ["evt_123", "evt_124"]
  }'

Response (202 Accepted)Important: Acknowledge only events you've successfully processed. Unacknowledged events will return in next polling.

3. Get order details

Detalhes do pedido

Obtenha os detalhes do pedido antes de confirmar ou cancelar. Use GET /orders/{id} para verificar itens, disponibilidade e endereço de entrega.Requisição:

curl -X GET "https://merchant-api.ifood.com.br/order/v1.0/orders/{id}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

Retorna 200 com todos os detalhes do pedido (itens, pagamento, endereço, etc.). Retorna 404 para IDs inválidos, pedidos indisponíveis ou antigos.

Pedido ainda não disponívelO evento PLACED pode chegar antes dos detalhes. Se receber 404, implemente retry com exponential backoff por até 10 minutos. Não faça retentativas infinitas para evitar bloqueios.

Pedidos antigosA API mantém detalhes por apenas 7 dias. Evite consultar repetidamente pedidos antigos para não sofrer rate limiting.

Detalhes de um pedido

Consulte todos os campos disponíveis

4. Print receipt

Before confirming, print receipt for kitchen:Use order structure obtained in previous step. Include:

Order ID (displayId)
Items with special instructions
Delivery mode (address/pickup)
Customer CPF/CNPJ (if required)

Recommended template: See example

5. Confirm order

Confirm receipt within 8 minutes. See confirmation deadline for details.

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/ord_456/confirm" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Response (202 Accepted)API returns immediately. Next polling shows result:

{
  "events": [
    {
      "code": "CONFIRMED",
      "orderId": "ord_456"
    }
  ]
}

On failure (e.g., inventory unavailable):

{
  "code": "CANCELLATION_REQUEST_FAILED",
  "metadata": { "reason": "Insufficient inventory" }
}

Common scenarios:

After 8 minutes → Order cancelled automatically
Duplicate call → Ignored (idempotent)
Expired token → 401 Unauthorized

Audit tip: Store orderId and timestamp for tracking.

6. Order lifecycle

FOOD

Estados:

PLACED — Pedido criado
CONFIRMED — Pedido confirmado
PREPARATION_STARTED — Preparo iniciado (opcional)
DISPATCHED — Saiu para entrega
READY_TO_PICKUP — Pronto para retirada
CONCLUDED — Concluído
CANCELLED — Cancelado

FOOD_SELF_SERVICE

Estados:

PLACED — Pedido criado
CONFIRMED — Pedido confirmado
READY_TO_PICKUP — Pronto para retirada
DELIVERED — Entregue
CONCLUDED — Concluído
CANCELLED — Cancelado

ANOTAI

Estados:

PLACED — Pedido criado
CONFIRMED — Pedido confirmado
DISPATCHED — Saiu para entrega
CONCLUDED — Concluído
CANCELLED — Cancelado

7. Order moment

Momento do pedido

Alguns pedidos devem ser preparados imediatamente, enquanto outros são agendados para uma data ou horário específico.

orderTiming	Descrição
`IMMEDIATE`	Prepare e entregue o mais breve possível
`SCHEDULED`	Respeite o horário agendado. Saiba mais sobre pedidos agendados

8. Prepare order

Preparar pedido

Pedidos de food passam por etapas específicas de preparação. Veja o diagrama abaixo:

Confirmar pedido

Use POST /orders/{id}/confirm para confirmar o pedido.Requisição:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/confirm" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

Retorna 202 Accepted.

Iniciar preparo

Use POST /orders/{id}/startPreparation to start preparation.Requisição:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/startPreparation" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

Retorna 202 Accepted.

Pedido pronto para entrega

Após preparar, notifique usando:Para delivery:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/dispatch" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

Para takeout:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/{id}/readyToPickup" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

Ambos retornam 202 Accepted.

9. Pick order

10. Notify order ready

Notify when preparation is complete.

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/ord_456/readyToPickup" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Required for: TAKEOUT and DINE_IN orders. Optional for DELIVERY with iFood driver.For merchant delivery, use /dispatch instead.Response (202 Accepted)

11. Dispatch merchant delivery

For merchant-managed delivery:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/ord_456/dispatch" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "deliveredBy": "MERCHANT" }'

Response (202 Accepted)System automatically marks as CONCLUDED after delivery.

12. Track delivery (iFood)

For orders delivered by iFood, track in real time:Prerequisite: Receive ASSIGN_DRIVER event (driver assigned)

curl -X GET "https://merchant-api.ifood.com.br/order/v1.0/orders/ord_456/tracking" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "latitude": -23.5505,
  "longitude": -46.6333,
  "expectedDelivery": "2024-04-25T18:30:00Z",
  "pickupEtaStart": 120,
  "deliveryEtaEnd": 600,
  "trackDate": "2024-04-25T18:15:00Z"
}

Limitations:

One request every 30 seconds (respect rate limiting)
May return 404 before available
Only during active delivery

13. Order cancellation

Check valid reasons

curl -X GET "https://merchant-api.ifood.com.br/order/v1.0/orders/ord_456/cancellationReasons" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "reasons": [
    { "code": "501", "description": "System error" },
    { "code": "502", "description": "Duplicate order" },
    { "code": "503", "description": "Item unavailable" }
    // ... more codes
  ]
}

Request cancellation

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/ord_456/requestCancellation" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "503"
  }'

Response (202 Accepted)Result arrives in next polling:

{
  "events": [
    {
      "code": "CANCELLED",  // Success
      "orderId": "ord_456"
    }
  ]
}

Restrictions:

Excessive cancellations incur penalties
Beyond a threshold, store is temporarily closed
Some periods have cancellation limits

Flow with diagram:

14. Validate pickup

If enabled, driver provides pickup code:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/ord_456/validatePickupCode" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "123456"
  }'

Validation: Compare with pickupCode in order details.Response (200 OK):

{ "valid": true }

15. Confirm delivery

iFood delivery

Automatic — driver confirms via app.

Merchant delivery

Share link with driver:

https://confirmacao-entrega-propria.ifood.com.br/

Print the localizer (phone.localizer) on receipt for reference.

Validate delivery

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/orders/ord_456/verifyDeliveryCode" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "654321"
  }'

Response (200 OK):

{ "valid": true }

After validation, system automatically marks as CONCLUDED.

16. Process order modifications

Customer removes/adds items after confirmation:

{
  "events": [
    {
      "code": "ORDER_PATCHED",
      "orderId": "ord_456",
      "metadata": {
        "changeType": "DELETE_ITEMS",
        "items": [
          {
            "id": "item_789",
            "name": "Burger",
            "quantity": 1
          }
        ]
      }
    }
  ]
}

Actions needed:

Update kitchen receipt (remove item)
Update billing system
Acknowledge event

17. Process post-delivery disputes

Customer disputes after delivery? Respond in negotiation:

curl -X POST "https://merchant-api.ifood.com.br/order/v1.0/disputes/dispute_123/accept" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "CUSTOMER_SATISFACTION",
    "detailReason": "Courtesy refund"
  }'

Response options:

/accept — Agree with cancellation
/reject — Disagree with proposal
/alternative — Offer refund or additional time

Critical: You have until expiresAt to respond. No response = automatic action (refund).Learn more: Negotiation Platform Guide

18. Automatic conclusion

iFood automatically marks as CONCLUDED after:

Type	Immediate	Scheduled
Restaurant + iFood	Delivery or 6h	6h after scheduling.to
Restaurant + Merchant	4h	4h after scheduling.to
Supermarket/Pharmacy	13h	13h after scheduling.to

All include deliveryTimeInSeconds (store setting).You'll receive CONCLUDED event:

{
  "code": "CONCLUDED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T19:00:00Z"
}

Next reading

Data structure — Complete order fields
Quick reference — Endpoints reference
All events — Event catalog
Negotiation — Handshake Platform Guide
Ready for prod? — Homologation criteria

Was this page helpful?

Rate your experience in the new Developer portal:

Implementation guide — Order API

1. Receive new orders

Polling (recommended to start)

Webhooks (scalable)

2. Acknowledge event consumption

3. Get order details

Detalhes do pedido

Detalhes de um pedido

4. Print receipt

5. Confirm order

6. Order lifecycle

FOOD

FOOD_SELF_SERVICE

ANOTAI

7. Order moment

Momento do pedido

8. Prepare order

Preparar pedido

Confirmar pedido

Iniciar preparo

Pedido pronto para entrega

9. Pick order

10. Notify order ready

11. Dispatch merchant delivery

12. Track delivery (iFood)

13. Order cancellation

Check valid reasons

Request cancellation

14. Validate pickup

15. Confirm delivery

iFood delivery

Merchant delivery

Validate delivery

16. Process order modifications

17. Process post-delivery disputes

18. Automatic conclusion

Implementation checklist

Next reading