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

7. Pick order

8. 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)

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

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

11. 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:

12. 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 }

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

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

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

16. 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: