Search in documentation
ctrl+4K
Modules
Authentication
Merchant
Catalog
Order
Events
Logistics
Shipping
Review
Financial
Solutions

Fundamentals

Understand core concepts before integrating. This guide explains what you need to know to work with orders.

What is the Order module

The Order module manages the complete order lifecycle — from receiving to delivery. It is required to integrate your store with the iFood platform.With this integration you can:
  • Receive orders in real time
  • Confirm or reject orders automatically
  • Track preparation and delivery
  • Resolve post-delivery issues (cancellations, refunds)
Important: Understand the concepts on this page before proceeding to the Implementation Guide.

Order types

Each order has an orderType that defines how the customer receives their items:
TypeDescriptionWhen to use
DELIVERYDelivery to customer addressRestaurants, markets with delivery service
TAKEOUTCustomer picks up at establishmentPickup counter or pickup area
DINE_INOn-premises consumptionRestaurants with dine-in service

Order categories

The category field identifies the merchant type:
CategoryOriginCharacteristics
FOODRestaurantsAll delivery types (DELIVERY, TAKEOUT, DINE_IN)
FOOD_SELF_SERVICEKiosks and self-checkoutAutomated self-service orders
GROCERYSupermarkets, pharmacies, pet shopsVirtual bag API; picking workflow
ANOTAIThird-party integrationsAggregator platform

Order lifecycle

Important: Each transition is triggered by events, not polling. You don't ask "what's the state?", you receive notifications when the state changes.

Order timing

Confirmation deadline (SLA)

Every order must be confirmed within 8 minutes:
  • IMMEDIATE orders: 8 minutes from createdAt
  • SCHEDULED orders: 8 minutes from preparationStartDateTime
Failure to confirm results in automatic cancellation and account penalties.How to implement: Workflow — Confirm order

Event-driven architecture

Instead of constantly asking the system for order status, the Order API works with events — iFood notifies you when the state changes.Communication pattern:
  • iFood publishes an event when something happens (new order, customer cancels, driver assigned, etc.)
  • You react to the event by calling an action (confirm, start preparation, etc.)
  • Your system stays synchronized without making unnecessary requests
Two ways to receive events:
  1. Polling — You check every 30 seconds if there are new events (simpler to start)
  2. Webhooks — iFood sends events to your endpoint (more scalable)
How to choose:
  • Start with polling while you develop
  • Migrate to webhooks when processing >1000 orders/day
How to implement: See Workflow — Get new orders for practical examples.

Main events

You need to recognize these events:
EventMeaningNext step
CONFIRMEDOrder arrived in your queueProcess in POS, confirm via API
CANCELLATION_REQUEST_FAILEDYour confirmation was rejectedResend confirmation or contact support
CANCELLEDOrder was cancelledRemove from queue, free resources
DELIVERY_GROUP_ASSIGNEDDelivery grouped with anotherUpdate delivery information
ASSIGN_DRIVERDriver assignedCan track delivery in real time
HANDSHAKE_DISPUTECustomer disputedRespond before expiresAt
Read more: Complete event catalog

Delivery tracking

For DELIVERY orders with iFood drivers:The system provides real-time tracking after the driver is assigned:
  • Event triggered: ASSIGN_DRIVER (driver assigned)
  • Data available: Latitude, longitude, estimated ETA, time until pickup and delivery
  • Limit: Maximum one request every 30 seconds
How to implement: See Workflow — Track driver for examples.

Dispute resolution (Handshake platform)

When a customer disputes an order after delivery, the system initiates a negotiation between you and the customer:
  • You receive HANDSHAKE_DISPUTE with the customer's proposal
  • You can accept, reject, or make a counteroffer (refund or additional time)
  • You have until expiresAt to respond
  • No response = automatic action (usually refund)
Important: Unanswered disputes generate chargebacks. Always respond, even to reject.
How to implement: See Negotiation Platform for API reference and Negotiation Platform Guide for practical examples.

Order modifications

Customer removes/adds items after confirmation? You receive ORDER_PATCHED with change details.Types of changes:
  • Quantity/unit modified
  • Item removed
  • Item added
  • Item replaced
Action needed: Update your billing/invoicing system to reflect changes.How to implement: See Workflow — Partial modifications for how to process.

Next steps

Now that you understand the concepts, choose your next step:
  1. Ready to implement? Complete workflow — step-by-step guide
  2. Looking for a specific endpoint? Endpoints reference
  3. Understanding order structure? Data structure
  4. Exploring all events? Event catalog
  5. Ready for production? Homologation criteria
Was this page helpful?
Rate your experience in the new Developer portal:
On this page
Fundamentals
What is the Order module
Order types
Order categories
Order lifecycle
Order timing
Confirmation deadline (SLA)
Event-driven architecture
Main events
Delivery tracking
Dispute resolution (Handshake platform)
Order modifications
Next steps
Content read0%