Search in documentation

Modules

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Solutions

Orders on iFood platform

Use this documentation to request iFood delivery drivers for orders that already exist on the platform. This flow is ideal when you have orders with orderId and want to contract iFood's logistics services for delivery.

How it works

The flow consists of three stages:

Check availability - Confirm delivery is available for the address
Request driver - Allocate an iFood driver to the order
Cancel (optional) - Cancel the request before driver acceptance

1. Check availability

Verify if delivery is available for the order and get price and estimated time information.

Why check?

This stage is essential for:

Validating that the address is within iFood coverage area
Identifying temporary unavailability (high demand, off-hours)
Obtaining price information and estimated time window
Avoiding failures in the driver request

Tip: We recommend always performing this check to improve request success rate and user experience.

Endpoint

GET /shipping/v1.0/orders/{orderId}/deliveryAvailabilities

Parameters

Parameter	Location	Type	Required	Description
`orderId`	path	uuid	Yes	ID of existing order on the platform

Example request

curl -X GET "https://merchant-api.ifood.com.br/shipping/v1.0/orders/{orderId}/deliveryAvailabilities" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Success response - 200 OK

Valid quote obtained successfully. Use the returned id as quoteId in the next stage.

Response fields

Field	Type	Description
`id`	uuid	Quote ID (use as `quoteId` in next stage)
`expirationAt`	datetime	Quote validity in UTC. Requesting after is invalid.
`createdAt`	datetime	Quote creation date in UTC
`distance`	integer	Delivery distance in meters
`preparationTime`	integer	Preparation time in seconds
`quote.grossValue`	decimal	Gross delivery value in reals
`quote.discount`	decimal	Applied discount in reals
`quote.raise`	decimal	Applied surcharge in reals
`quote.netValue`	decimal	Net value = grossValue - discount + raise
`deliveryTime.min`	integer	Estimated minimum delivery time in seconds
`deliveryTime.max`	integer	Estimated maximum delivery time in seconds
`hasPaymentMethods`	boolean	Indicates if payment methods are available
`paymentMethods[].id`	uuid	Unique payment method ID
`paymentMethods[].brand`	string	Card brand (e.g., Visa, Mastercard)
`paymentMethods[].liability`	string	Payment responsible party (e.g., IFOOD)
`paymentMethods[].paymentType`	string	Payment type (e.g., OFFLINE for cash on delivery)
`paymentMethods[].method`	string	Payment method: CREDIT or DEBIT

Example response

{
  "id": "57cd1046-2e06-446f-a2dd-18a518212c3c",
  "expirationAt": "2023-08-18T19:49:06Z",
  "createdAt": "2023-08-17T19:49:06Z",
  "distance": 3000,
  "preparationTime": 60,
  "quote": {
    "grossValue": 7.99,
    "discount": 0,
    "raise": 0,
    "netValue": 7.99
  },
  "deliveryTime": {
    "min": 1200,
    "max": 1800
  },
  "hasPaymentMethods": true,
  "paymentMethods": [
    {
      "id": "21c65a8c-f29e-463f-b0bd-240edeb593c4",
      "brand": "Visa",
      "liability": "IFOOD",
      "paymentType": "OFFLINE",
      "method": "CREDIT"
    }
  ]
}

Interpreting the response:

Distance: 3km
Price: R$ 7.99 (no discount)
Estimated time: 20-30 minutes
Payment methods: 1 Visa card available

Errors - 400 Bad Request

The API returns 400 Bad Request when delivery is not available. Check the error codes to determine the cause.

For detailed solutions for each error, consult Best practices and troubleshooting.

Error codes

Code	Description	Recommended Action
BadRequest	Problem in request	Verify if `orderId` is in correct format
BadRequestMerchant	Your store is temporarily unavailable	Check store status in dashboard
DeliveryDistanceTooHigh	Address more than ~10km from store	Confirm address with customer
OffOpeningHours	Outside operating hours	Try again during business hours
OriginNotFound	Store not found in logistics area	Register your store in iFood areas
ServiceAreaMismatch	Address outside iFood coverage	Confirm if region has iFood delivery
HighDemand	Logistics saturated temporarily	Try again in a few minutes
MerchantStatusAvailability	Your account has pending issues	Contact iFood support
InvalidPaymentMethods	Payment method not supported	Use another payment method
SaturatedOfflinePayment	Cash on delivery unavailable	Switch to another method
NRELimitExceeded	Limit of simultaneous drivers reached	Wait for ongoing deliveries to complete

Example error

{
  "code": "DeliveryDistanceTooHigh",
  "message": "On Demand unavailable: delivery address is more than 10 km from your store.",
  "details": ["Delivery distance too high"]
}

Internal error - 500 Internal Server Error

Temporary server error. Try again in a few seconds.

{
  "code": "InternalServerError",
  "message": "Oops. There was a failure. Please try again in a few moments.",
  "details": ["Internal server error"]
}

What to do: Implement automatic retry with exponential backoff. After 3-5 failed attempts, log and notify support.

2. Request driver

After obtaining the quote from the previous stage, request the allocation of an iFood driver.

Asynchronous operation:

The immediate response is just an acknowledgment (202 Accepted)
A driver will be allocated automatically in the background
Monitor events to know the final result (success or failure)

Endpoint

POST /shipping/v1.0/orders/{orderId}/requestDriver

Parameters

Parameter	Location	Type	Required	Description
`orderId`	path	uuid	Yes	ID of existing order on the platform
`quoteId`	body	uuid	Yes	Quote ID obtained in previous stage (valid ~24h)

Example request

curl -X POST "https://merchant-api.ifood.com.br/shipping/v1.0/orders/{orderId}/requestDriver" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "57cd1046-2e06-446f-a2dd-18a518212c3c"
  }'

Body:

{
  "quoteId": "57cd1046-2e06-446f-a2dd-18a518212c3c"
}

Response - 202 Accepted

Request registered successfully. A driver is being allocated.Next steps: Monitor event polling for the following events:

Event	Meaning	Action
REQUEST_DRIVER	Request registered in system	Processing started
REQUEST_DRIVER_SUCCESS	Driver successfully allocated	Delivery will proceed as quoted
REQUEST_DRIVER_FAILED	Driver allocation failed	Try again or use another service

Important: Lack of quick response doesn't mean failure. Processing is asynchronous and can take minutes.

Errors - 400 Bad Request

Invalid request or service unavailable. Check the error code for details.

For detailed solutions for each error, consult Best practices and troubleshooting.

Code	Description	Recommended Action
BadRequest	Invalid data in request	Validate `orderId` and `quoteId`
BadRequestCustomer	Customer unavailable at the moment	Check customer data
BadRequestMerchant	Your store is unavailable	Check store status
DeliveryDistanceTooHigh	Address outside coverage	Confirm customer address
HighDemand	Logistics saturated now	Wait minutes and try again
MerchantEasyDeliveryDisabled	Service not enabled for your store	Enable service in dashboard
OffOpeningHours	Outside operating hours	Wait for business hours
OriginNotFound	Store not located	Register store in iFood areas
ServiceAreaMismatch	Address outside service area	Check iFood coverage in region
MerchantStatusAvailability	Your account has restrictions	Contact support
InvalidPaymentMethods	Payment method not supported	Use another payment method
SaturatedOfflinePayment	Cash on delivery unavailable	Switch to another method
NRELimitExceeded	Limit of simultaneous drivers reached	Wait for ongoing deliveries to complete

Example error

{
  "code": "HighDemand",
  "message": "iFood logistics is temporarily unavailable. Please try again later.",
  "details": ["High demand"]
}

Retry strategy: For transient errors (like HighDemand, OffOpeningHours), implement automatic retry with exponential backoff.

3. Cancel request

Cancel the driver allocation without canceling the order itself. Ideal when preparation was faster or slower than expected.

Critical restrictions:

Cancellation is only possible before driver acceptance
After driver accepts, follow Order cancellation rules
No fee for cancellations before acceptance
The action is permanent and irreversible

Endpoint

POST /shipping/v1.0/orders/{orderId}/cancelRequestDriver

Parameters

Parameter	Location	Type	Required	Description
`orderId`	path	uuid	Yes	ID of order to cancel delivery

Example request

curl -X POST "https://merchant-api.ifood.com.br/shipping/v1.0/orders/{orderId}/cancelRequestDriver" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Response - 202 Accepted

Cancellation request registered successfully. Processing occurs in the background.Monitor events for confirmation:

Event	Meaning	Action
DELIVERY_CANCELLATION_REQUESTED	Cancellation requested from system	Processing started
DELIVERY_CANCELLATION_REQUEST_ACCEPTED	Cancellation accepted and processed	Delivery was cancelled, no fee
DELIVERY_CANCELLATION_REQUEST_REJECTED	Cancellation rejected by system	Driver already accepted; follow standard workflow

For more details: See Delivery events.

Errors - 400 Bad Request

Invalid request. Verify the orderId sent.

{
  "code": "BadRequest",
  "message": "There was a problem requesting cancellation. Check the information sent.",
  "details": ["Field 'OrderID' must be in uuid format."]
}

Validation: Ensure that orderId is a valid UUID in format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Internal error - 500 Internal Server Error

Temporary server error.

{
  "code": "InternalServerError",
  "message": "Oops. There was a failure. Please try again in a few moments.",
  "details": ["Internal server error"]
}

What to do: Implement automatic retries. After 3-5 attempts, log and notify support.

Next steps

Integration complete?

Implement event polling to monitor status in real-time
Consult the delivery tracking guide for location information
Review the complete order flow to understand the lifecycle

Questions?

Explore the complete API reference
Consult the shipping technical documentation
Contact support

Was this page helpful?

Rate your experience in the new Developer portal: