Search in documentation

Modules

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Solutions

Scheduled orders

Let customers choose delivery time to optimize operations during peak hours and improve experience.

What is a scheduled order

Scheduled order is when a customer chooses an exact time to receive or pick up their order, instead of immediate delivery/pickup. Works with:

DELIVERY: Delivery at scheduled time
TAKEOUT: Pickup at scheduled time
DINE_IN: On-premises consumption at reserved time

Critical: Respect customer's time. Never prepare or deliver early.

Identify scheduled order

Check orderTiming and scheduled object:

{
  "orderTiming": "SCHEDULED",
  "scheduled": {
    "deliveryDateTimeStart": "2024-04-25T19:00:00Z",
    "deliveryDateTimeEnd": "2024-04-25T19:30:00Z",
    "preparationStartDateTime": "2024-04-25T18:45:00Z"
  },
  "orderType": "DELIVERY"
}

Field	Meaning
`orderTiming = "SCHEDULED"`	Order is scheduled
`deliveryDateTimeStart`	Delivery/pickup window start
`deliveryDateTimeEnd`	Delivery/pickup window end
`preparationStartDateTime`	When you should start preparation

Step-by-step flow

1. Confirm order

Confirm receipt within 8 minutes from preparationStartDateTime. See confirmation deadline.

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

Response: 202 Accepted

2. Check preparation recommendation

If "Smart Preparation" is enabled, system calculates best time:

{
  "RECOMMENDED_PREPARATION_START": "2024-04-25T18:45:00Z"
}

Use as reference, but respect preparationStartDateTime if more restrictive.

3. Start preparation

Begin preparation at correct time:

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

Timing:

Never before preparationStartDateTime
Start near calculated time
Finish near deliveryDateTimeStart

Response: 202 Accepted

4. Notify ready

When done:For DELIVERY:

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

For TAKEOUT/DINE_IN:

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

Response: 202 Accepted

Critical deadline calculation

The key to scheduled orders is understanding preparationStartDateTime:

Formula

preparationStartDateTime = deliveryDateTimeStart − deliveryTime

Where deliveryTime is average preparation duration (in minutes).

Practical example

Scenario: Customer schedules delivery for 20:00, your store takes 40 minutes to prepare

Scheduled delivery: 20:00
Preparation time: 40 minutes
─────────────────────────
Start prep at: 19:20
SLA deadline: 19:28 (8 min after 19:20)

Expected timeline:

16:00 → Customer schedules for 20:00 in app
16:01 → You receive CONFIRMED
16:02 → Confirm order (within 8 min after 19:20)
19:00 → System alerts: "start prep in 20 min"
19:20 → Receipt prints — start preparation
19:20 → Call /startPreparation
19:28 → SLA deadline passed (not a problem, already confirmed at 16:02)
20:00 → Call /dispatch or /readyToPickup
20:00 → Driver arrives or customer picks up

Important rules

Never prepare early

Wrong: Start prep before preparationStartDateTime

Customer may not be home (DELIVERY)
Food gets cold/warm
Customer sees order leaving early than scheduled

Correct: Start exactly at preparationStartDateTime or shortly after

Respect the window

{
  "deliveryDateTimeStart": "2024-04-25T19:00:00Z",
  "deliveryDateTimeEnd": "2024-04-25T19:30:00Z"
}

System allows delivery during entire window, but respect start time.

Order confirmation (8-minute SLA)

Although you confirm right away, technical SLA is:

8 minutes after preparationStartDateTime

This allows time to:

Validate item availability
Alert customer if there's delay

You already confirmed early (16:02 in example), so you're covered.

Common scenarios

Scenario 1: On-time scheduled delivery

16:00 → Customer schedules for 20:00
16:01 → Receive CONFIRMED
16:02 → Confirm via API
19:20 → Get alert "start prep"
19:20 → Call /startPreparation
19:50 → Prep done
20:00 → Call /dispatch exactly
20:15 → Driver arrives and picks up
20:40 → Customer receives

Scenario 2: Scheduled takeout with margin

17:00 → Customer schedules for 19:30
17:01 → Receive CONFIRMED
17:02 → Confirm
19:00 → Get alert "start prep in 30 min"
19:30 → Call /startPreparation (15 min early to be ready)
19:45 → Prep done
19:50 → Call /readyToPickup
20:00 → Customer arrives, picks up at counter

Scenario 3: 30-minute window

13:00 → Customer schedules 18:00-18:30
13:01 → Receive CONFIRMED
13:02 → Confirm
17:20 → Receipt prints (40 min early)
17:20 → Call /startPreparation
18:00 → Prep done
18:00 → Call /dispatch
18:15 → Driver picks up (within window)
18:40 → Customer receives (within window)

POS integration

Map states

State	Your POS	Action
PLACED	Scheduled	Show in calendar
CONFIRMED	Confirmed	Mark confirmed
PREPARING	Preparing	Send to kitchen with time
READY_TO_PICKUP	Ready	Alert "ready for X"
DISPATCHED	Left	Mark dispatched
CONCLUDED	Delivered	Archive

Notify team

Print on receipt:

═════════════════════════
  SCHEDULED ORDER
═════════════════════════

ID: #12345
Customer: John Silva

Scheduled for: 20:00
Start prep at: 19:20
Max deadline: 19:28

[ITEMS]
- Burger x1
- Soft Drink x1

═════════════════════════

Testing and validation

Before going live

Test with orderTiming = "SCHEDULED"
Validate preparationStartDateTime calculation
Test IMMEDIATE too (to not break it)
Verify /startPreparation respects timing
Test dispatch/readyToPickup at correct time
Test DELIVERY, TAKEOUT, DINE_IN scheduled
Validate 8-minute SLA

Debugging tips

If order gets cancelled:

Check if you confirmed within 8 minutes of preparationStartDateTime
Check if preparationStartDateTime was calculated correctly
Check timezone (always UTC in API)

Next reading

Scheduled takeout — For pickup
General flow — Implementation guide
Order details — Complete structure
API reference — Endpoints
Schedule events — Event catalog

Was this page helpful?

Rate your experience in the new Developer portal: