Search in documentation

Modules

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Solutions

Order events

Understand all events that iFood sends during the order lifecycle. This reference shows structure, meaning, and required actions for each event.

How to receive events

Choose a method:Polling (checking periodically):

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

Webhooks (iFood sends to you): Register an HTTPS endpoint. iFood will send POST to: https://your-server.com/webhooks/ordersSee complete implementation guide

Event structure

All events share this base structure:

{
  "id": "evt_abc123",
  "code": "CONFIRMED",
  "fullCode": "ORDER_CONFIRMED",
  "orderId": "ord_789",
  "createdAt": "2024-04-25T18:00:00Z",
  "metadata": {
    // Event-specific content
  }
}

Field	Type	Description
`id`	string	Unique event identifier
`code`	string	Short event code (ex: `CONFIRMED`)
`fullCode`	string	Complete code (ex: `ORDER_CONFIRMED`)
`orderId`	string	Related order ID
`createdAt`	ISO 8601	UTC timestamp when event was created
`metadata`	object	Event-specific data

Note about dates: All timestamps are in UTC (ISO 8601). Convert to local time as needed.

Quick reference — All events

Use this table to quickly find an event:

Code	Meaning	When it occurs	Action needed
`CONFIRMED`	Order confirmed	New order arrives	Process in POS
`CANCELLED`	Order cancelled	Customer/system cancels	Remove from queue
`SEPARATION_STARTED`	Preparation started	You called `/startPreparation`	None
`SEPARATION_ENDED`	Preparation finished	You called `/readyToPickup`	None
`READY_TO_PICKUP`	Ready for pickup	System confirms readiness	Notify customer
`DISPATCHED`	Dispatched	You called `/dispatch`	Track delivery
`CONCLUDED`	Concluded	Delivery confirmed/Timeout	Archive order
`CANCELLATION_REQUESTED`	Cancellation requested	Customer/you requested	Validate reason
`CANCELLATION_REQUEST_FAILED`	Cancellation rejected	System rejected	Try again
`ASSIGN_DRIVER`	Driver assigned	iFood assigned driver	Share tracking
`GOING_TO_ORIGIN`	Going to origin	Driver on the way	Prepare order
`ARRIVED_AT_ORIGIN`	Arrived at store	Driver at door	Finalize
`COLLECTED`	Collected	Driver picked up order	None
`ARRIVED_AT_DESTINATION`	Arrived at destination	Driver at delivery location	None
`DELIVERY_RETURNING_TO_ORIGIN`	Returning to store	Return in progress	Receive order
`HANDSHAKE_DISPUTE`	Dispute opened	Customer disputes post-delivery	Respond before expiry
`HANDSHAKE_SETTLEMENT`	Dispute resolved	System resolved negotiation	Archive
`ORDER_PATCHED`	Order modified	Customer added/removed items	Update billing
`DELIVERY_ADDRESS_CHANGE`	Address changed	Customer changed address	Update data
`DELIVERY_PHONE_CHANGE`	Phone changed	Customer changed phone	Update contact
`RECOMMENDED_PREPARATION_START`	Preparation recommended	System calculated best time	Use if available
`PREPARATION_STARTED`	Preparation started	System detected start	None

Order status — Main events

These events mark state transitions in the order:

CONFIRMED

Code: ORDER_CONFIRMEDNew order arrived in your queue.

{
  "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": [
      {
        "id": "item_789",
        "name": "Burger",
        "quantity": 1,
        "price": 25.50
      }
    ],
    "customer": {
      "id": "cust_123",
      "name": "John Silva",
      "phone": "+55 11 99999-8888"
    },
    "deliveryAddress": {
      "address": "Flower Street 123",
      "city": "São Paulo",
      "zipcode": "01234-567"
    },
    "createdAt": "2024-04-25T18:00:00Z"
  }
}

Next actions:

Process order in your POS/system
Print receipt for kitchen
Call /confirm within 8 minutes See how

Critical deadline: 8 minutes to call /confirm, or order is automatically cancelled.

SEPARATION_STARTED

Code: PREPARATION_STARTEDYou started preparation (called /startPreparation).

{
  "id": "evt_124",
  "code": "SEPARATION_STARTED",
  "fullCode": "PREPARATION_STARTED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:05:00Z",
  "metadata": {
    "id": "ord_456",
    "status": "PREPARING",
    "startedAt": "2024-04-25T18:05:00Z"
  }
}

Next actions:

None (informational)
Continue with preparation

SEPARATION_ENDED

Code: PREPARATION_ENDEDYou marked as ready (called /readyToPickup).

{
  "id": "evt_125",
  "code": "SEPARATION_ENDED",
  "fullCode": "PREPARATION_ENDED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:15:00Z",
  "metadata": {
    "id": "ord_456",
    "status": "READY_TO_PICKUP",
    "readyAt": "2024-04-25T18:15:00Z"
  }
}

Next actions:

Notify customer that order is ready
Wait for pickup (TAKEOUT) or driver (DELIVERY)

DISPATCHED

Code: DISPATCHEDOrder was dispatched (driver left with order or customer picked up).

{
  "id": "evt_126",
  "code": "DISPATCHED",
  "fullCode": "DISPATCHED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:20:00Z",
  "metadata": {
    "id": "ord_456",
    "status": "DISPATCHED",
    "dispatchedAt": "2024-04-25T18:20:00Z",
    "deliveredBy": "MERCHANT" // or "IFOOD"
  }
}

Next actions:

If merchant delivery: track driver to destination
If iFood: wait for delivery confirmation event

CONCLUDED

Code: CONCLUDEDOrder was finished (delivered or picked up successfully).

{
  "id": "evt_127",
  "code": "CONCLUDED",
  "fullCode": "CONCLUDED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:45:00Z",
  "metadata": {
    "id": "ord_456",
    "status": "CONCLUDED",
    "concludedAt": "2024-04-25T18:45:00Z",
    "totalPrice": 25.50,
    "totalValue": 25.50
  }
}

Next actions:

Archive order
No further action needed

CANCELLED

Code: ORDER_CANCELLEDOrder was cancelled.

{
  "id": "evt_128",
  "code": "CANCELLED",
  "fullCode": "ORDER_CANCELLED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:50:00Z",
  "metadata": {
    "id": "ord_456",
    "status": "CANCELLED",
    "cancelledAt": "2024-04-25T18:50:00Z",
    "cancelReason": "503",
    "cancelReasonDescription": "Item unavailable"
  }
}

Next actions:

Remove order from queue
Free resources (reserved items, etc.)
Refund customer

Cancellation — Control events

CANCELLATION_REQUESTED

Code: CANCELLATION_REQUESTEDYou or customer requested cancellation.

{
  "id": "evt_129",
  "code": "CANCELLATION_REQUESTED",
  "fullCode": "CANCELLATION_REQUESTED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:05:00Z",
  "metadata": {
    "id": "ord_456",
    "reason": "503",
    "reasonDescription": "Item unavailable"
  }
}

Next actions:

Wait for confirmation (CANCELLED) or rejection (CANCELLATION_REQUEST_FAILED)

CANCELLATION_REQUEST_FAILED

Code: CANCELLATION_REQUEST_FAILEDSystem rejected your cancellation attempt.

{
  "id": "evt_130",
  "code": "CANCELLATION_REQUEST_FAILED",
  "fullCode": "CANCELLATION_REQUEST_FAILED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:05:30Z",
  "metadata": {
    "id": "ord_456",
    "reason": "Order was already being prepared",
    "attemptedReason": "503"
  }
}

Next actions:

Investigate why cancellation was rejected
Try again if it's a transient reason
Contact support if it's a permanent block

Delivery — Tracking events (iFood)

These events occur when iFood is delivering the order:

ASSIGN_DRIVER

Code: ASSIGN_DRIVERiFood assigned a driver to the order.

{
  "id": "evt_131",
  "code": "ASSIGN_DRIVER",
  "fullCode": "ASSIGN_DRIVER",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:20:00Z",
  "metadata": {
    "id": "ord_456",
    "driver": {
      "id": "drv_123",
      "name": "Carlos Driver",
      "phone": "+55 11 91111-2222",
      "vehicle": "Motorcycle"
    },
    "deliveryDistance": 2.5,
    "estimatedDeliveryTime": 900
  }
}

Next actions:

Share tracking data with customer
Start calling /tracking every 30 seconds if needed

See how to track

GOING_TO_ORIGIN

Code: GOING_TO_ORIGINDriver is going to your store (pickup).

{
  "id": "evt_132",
  "code": "GOING_TO_ORIGIN",
  "fullCode": "GOING_TO_ORIGIN",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:20:30Z",
  "metadata": {
    "id": "ord_456",
    "driver": {
      "id": "drv_123"
    },
    "estimatedArrivalTime": 300
  }
}

Next actions:

Prepare order for driver
Have receipt printed
Validate driver's ID

ARRIVED_AT_ORIGIN

Code: ARRIVED_AT_ORIGINDriver arrived at your store.

{
  "id": "evt_133",
  "code": "ARRIVED_AT_ORIGIN",
  "fullCode": "ARRIVED_AT_ORIGIN",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:25:00Z",
  "metadata": {
    "id": "ord_456",
    "driver": {
      "id": "drv_123"
    },
    "arrivedAt": "2024-04-25T18:25:00Z"
  }
}

Next actions:

Hand order to driver
Ask driver to validate pickup code (if enabled)

See pickup validation

COLLECTED

Code: COLLECTEDDriver picked up the order at your store.

{
  "id": "evt_134",
  "code": "COLLECTED",
  "fullCode": "COLLECTED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:25:30Z",
  "metadata": {
    "id": "ord_456",
    "driver": {
      "id": "drv_123"
    },
    "collectedAt": "2024-04-25T18:25:30Z"
  }
}

Next actions:

None (informational)

ARRIVED_AT_DESTINATION

Code: ARRIVED_AT_DESTINATIONDriver arrived at customer's address.

{
  "id": "evt_135",
  "code": "ARRIVED_AT_DESTINATION",
  "fullCode": "ARRIVED_AT_DESTINATION",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:40:00Z",
  "metadata": {
    "id": "ord_456",
    "driver": {
      "id": "drv_123"
    },
    "arrivedAt": "2024-04-25T18:40:00Z"
  }
}

Next actions:

None (customer will receive from driver)

DELIVERY_RETURNING_TO_ORIGIN

Code: DELIVERY_RETURNING_TO_ORIGINDriver is returning to store (return in progress).

{
  "id": "evt_136",
  "code": "DELIVERY_RETURNING_TO_ORIGIN",
  "fullCode": "DELIVERY_RETURNING_TO_ORIGIN",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:45:00Z",
  "metadata": {
    "id": "ord_456",
    "driver": {
      "id": "drv_123"
    },
    "returningReason": "Customer not available"
  }
}

Next actions:

Prepare to receive order back
Investigate reason for return

DELIVERY_RETURNED_TO_ORIGIN

Code: DELIVERY_RETURNED_TO_ORIGINOrder was returned to your store.

{
  "id": "evt_137",
  "code": "DELIVERY_RETURNED_TO_ORIGIN",
  "fullCode": "DELIVERY_RETURNED_TO_ORIGIN",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:50:00Z",
  "metadata": {
    "id": "ord_456",
    "driver": {
      "id": "drv_123"
    },
    "returnedAt": "2024-04-25T18:50:00Z",
    "reason": "Customer not found"
  }
}

Next actions:

Receive and inspect order
Contact customer for second delivery attempt
Possible cancellation dispute

Dispute — Handshake platform

HANDSHAKE_DISPUTE

Code: HANDSHAKE_DISPUTECustomer opened a dispute (typically post-delivery).

{
  "id": "evt_138",
  "code": "HANDSHAKE_DISPUTE",
  "fullCode": "HANDSHAKE_DISPUTE",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T19:00:00Z",
  "metadata": {
    "disputable": true,
    "dispute": {
      "id": "dispute_123",
      "orderId": "ord_456",
      "status": "OPEN",
      "reason": "Order arrived wrong",
      "proposalValue": 50.00,
      "expiresAt": "2024-04-26T19:00:00Z",
      "createdAt": "2024-04-25T19:00:00Z"
    }
  }
}

Next actions:

Review customer's proposal
Respond before expiresAt with /accept, /reject, or /alternative
See negotiation platform guide

Critical warning: No response = automatic refund. Always respond.

HANDSHAKE_SETTLEMENT

Code: HANDSHAKE_SETTLEMENTDispute was resolved (by acceptance, rejection, or timeout).

{
  "id": "evt_139",
  "code": "HANDSHAKE_SETTLEMENT",
  "fullCode": "HANDSHAKE_SETTLEMENT",
  "orderId": "ord_456",
  "createdAt": "2024-04-26T19:05:00Z",
  "metadata": {
    "dispute": {
      "id": "dispute_123",
      "status": "SETTLED",
      "resolution": "MERCHANT_ACCEPTED",
      "settledAt": "2024-04-26T19:05:00Z"
    }
  }
}

Next actions:

Archive order
Record refund if accepted

Address and contact — Changes

DELIVERY_ADDRESS_CHANGE

Code: DELIVERY_ADDRESS_CHANGECustomer changed delivery address.

{
  "id": "evt_140",
  "code": "DELIVERY_ADDRESS_CHANGE",
  "fullCode": "DELIVERY_ADDRESS_CHANGE",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:10:00Z",
  "metadata": {
    "id": "ord_456",
    "newAddress": {
      "address": "New Street 456",
      "city": "São Paulo",
      "zipcode": "01500-000",
      "number": "456",
      "complement": "Apt 200"
    },
    "oldAddress": {
      "address": "Flower Street 123",
      "city": "São Paulo",
      "zipcode": "01234-567"
    }
  }
}

Next actions:

Update address in your system
Share new address with driver

DELIVERY_PHONE_CHANGE

Code: DELIVERY_PHONE_CHANGECustomer changed delivery contact phone.

{
  "id": "evt_141",
  "code": "DELIVERY_PHONE_CHANGE",
  "fullCode": "DELIVERY_PHONE_CHANGE",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:10:00Z",
  "metadata": {
    "id": "ord_456",
    "newPhone": "+55 11 98888-7777",
    "oldPhone": "+55 11 99999-8888"
  }
}

Next actions:

Update phone in your system
Share new phone with driver

Modifications — Order changes

ORDER_PATCHED

Code: ORDER_PATCHEDCustomer added, removed, or modified items after confirmation.Example 1: Item removed

{
  "id": "evt_142",
  "code": "ORDER_PATCHED",
  "fullCode": "ORDER_PATCHED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:08:00Z",
  "metadata": {
    "id": "ord_456",
    "changeType": "DELETE_ITEMS",
    "items": [
      {
        "id": "item_789",
        "name": "Drink",
        "quantity": 1,
        "price": 5.00
      }
    ],
    "newTotal": 20.50,
    "oldTotal": 25.50
  }
}

Example 2: Item added

{
  "id": "evt_143",
  "code": "ORDER_PATCHED",
  "fullCode": "ORDER_PATCHED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:08:30Z",
  "metadata": {
    "id": "ord_456",
    "changeType": "ADD_ITEMS",
    "items": [
      {
        "id": "item_999",
        "name": "Dessert",
        "quantity": 1,
        "price": 8.00
      }
    ],
    "newTotal": 28.50,
    "oldTotal": 20.50
  }
}

Example 3: Quantity modified

{
  "id": "evt_144",
  "code": "ORDER_PATCHED",
  "fullCode": "ORDER_PATCHED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:09:00Z",
  "metadata": {
    "id": "ord_456",
    "changeType": "UPDATE_ITEMS",
    "items": [
      {
        "id": "item_789",
        "name": "Burger",
        "oldQuantity": 1,
        "newQuantity": 2,
        "price": 25.50
      }
    ],
    "newTotal": 51.00,
    "oldTotal": 25.50
  }
}

Next actions:

Update receipt in kitchen
Update billing system
Confirm reading via /acknowledgment
If in preparation: adjust estimated time

Preparation — Informational events

RECOMMENDED_PREPARATION_START

Code: RECOMMENDED_PREPARATION_STARTSystem recommends ideal time to start preparation (for scheduled orders).

{
  "id": "evt_145",
  "code": "RECOMMENDED_PREPARATION_START",
  "fullCode": "RECOMMENDED_PREPARATION_START",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:00:00Z",
  "metadata": {
    "id": "ord_456",
    "recommendedStartTime": "2024-04-25T18:15:00Z",
    "scheduledDeliveryTime": "2024-04-25T18:45:00Z"
  }
}

Next actions:

Use as reference to start preparation (optional)
Respect preparationStartDateTime from order if more restrictive

See how to use

PREPARATION_STARTED

Code: PREPARATION_STARTEDSystem detected that preparation started (may be automatic in some POS systems).

{
  "id": "evt_146",
  "code": "PREPARATION_STARTED",
  "fullCode": "PREPARATION_STARTED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:15:00Z",
  "metadata": {
    "id": "ord_456",
    "startedAt": "2024-04-25T18:15:00Z"
  }
}

Next actions:

None (informational)

Delivery groups — Consolidation events

DELIVERY_GROUP_ASSIGNED

Code: DELIVERY_GROUP_ASSIGNEDYour order was grouped with another order for joint delivery (same route).

{
  "id": "evt_147",
  "code": "DELIVERY_GROUP_ASSIGNED",
  "fullCode": "DELIVERY_GROUP_ASSIGNED",
  "orderId": "ord_456",
  "createdAt": "2024-04-25T18:20:00Z",
  "metadata": {
    "id": "ord_456",
    "deliveryGroupId": "group_789",
    "groupedOrders": ["ord_456", "ord_457", "ord_458"],
    "estimatedDeliveryTime": 1200
  }
}

Next actions:

Update customer's delivery estimate
Prepare for joint delivery

Checklist — Critical events to respond to

Mark when your integration handles each one:

CONFIRMED — Process new order
CANCELLATION_REQUEST_FAILED — Try again
HANDSHAKE_DISPUTE — Respond before expiry
DELIVERY_ADDRESS_CHANGE — Update data
ORDER_PATCHED — Update billing
CANCELLATION_REQUESTED — Validate reason
ASSIGN_DRIVER — Share tracking
CANCELLED — Remove from queue

Next reading

How to receive events — Implementation guide
Respond to disputes — Negotiation platform
Validations and tracking — Endpoints reference
Concepts — Fundamentals
Data structure — Order details

Was this page helpful?

Rate your experience in the new Developer portal: