Search in documentation

Modules

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Solutions

Shipping

Orders outside iFood platform

This section explains how to integrate orders placed outside the iFood platform (without pre-existing orderId) to the On Demand delivery service.

Integration flow

1. Check availability

Before registering the order, check delivery availability to validate coverage and get estimates.

Why check?

Validate coverage area
Identify temporary unavailability
Get time and cost estimates
Avoid registration errors

Although optional, this check prevents errors and allows better operational planning.

Endpoint

GET /shipping/v1.0/merchants/{merchantId}/deliveryAvailabilities?latitude={lat}&longitude={lng}

Required parameters:

merchantId (path) - Merchant ID
latitude (query) - Delivery address latitude
longitude (query) - Delivery address longitude

Success response - 200 OK

Response fields

Field	Type	Description
id	uuid	Quote ID
expirationAt	datetime	Quote validity (UTC)
createdAt	datetime	Creation date (UTC)
distance	integer	Distance in meters
preparationTime	integer	Preparation time in seconds
quote.grossValue	decimal	Gross value
quote.discount	decimal	Discount
quote.raise	decimal	Surcharge
quote.netValue	decimal	Net value
deliveryTime.min	integer	Minimum delivery time (seconds)
deliveryTime.max	integer	Maximum delivery time (seconds)
hasPaymentMethods	boolean	Indicates available payment methods
paymentMethods[].method	string	CREDIT, DEBIT or CASH

Example

{
  "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"
    },
    {
      "id": "93c1c7c7-61f1-4dd9-bb84-62a03254701d",
      "liability": "IFOOD",
      "paymentType": "OFFLINE",
      "method": "CASH"
    }
  ]
}

Errors - 400 Bad Request

Error codes

Code	Description
BadRequest	Request problem. Check data
BadRequestMerchant	Merchant unavailable
DeliveryDistanceTooHigh	Address outside coverage area
OffOpeningHours	Outside operating hours
OriginNotFound	Store outside logistics area
ServiceAreaMismatch	Address outside coverage area
HighDemand	Logistics temporarily unavailable
MerchantStatusAvailability	Merchant with pending issue
InvalidPaymentMethods	Payment method not accepted
NRELimitExceeded	Driver limit reached
UnavailableFleet	Fleet unavailable

2. Register order

A driver will be allocated automatically after registration
If delivery is not possible, the order will not be registered
Make sure to validate data before sending

Delivery confirmation code

For security, a confirmation code (last 4 digits of phone) is automatically generated.

How it works

With code (default):

Send customer.phone.type="CUSTOMER" with valid phone
Driver will request the code on delivery
Customer must be informed beforehand

Without code:

Send customer.phone.type="STORE"
Code will not be requested

Inform the customer that the driver will request the last 4 digits of their phone. Validation failure may result in cancellation.

For partners without iFood tracking page

Consume the DELIVERY_DROP_CODE_REQUESTED event with metadata.CODE to make the code available to the customer.

Endpoint

POST /shipping/v1.0/merchants/{merchantId}/orders

Order fields

Required fields marked with *

Customer

Field	Type	Description
customer.name*	string	Name (max. 50 characters)
customer.phone.type	string	CUSTOMER (default) or STORE
customer.phone.countryCode*	string	Country code (2 digits). Ex: 55
customer.phone.areaCode*	string	Area code (2 digits). Ex: 11
customer.phone.number*	string	Phone (7-9 digits)

* Not required if customer.phone.type="STORE"

Delivery

Field	Type	Description
delivery.merchantFee*	float	Partner fee
delivery.preparationTime	integer	Preparation time (seconds)
delivery.quoteId	uuid	Quote ID
delivery.deliveryAddress.postalCode*	string	ZIP code (8 digits)
delivery.deliveryAddress.streetNumber*	string	Number
delivery.deliveryAddress.streetName*	string	Street (max. 50 characters)
delivery.deliveryAddress.complement	string	Complement (max. 50 characters)
delivery.deliveryAddress.reference	string	Reference (max. 70 characters)
delivery.deliveryAddress.neighborhood*	string	Neighborhood (max. 50 characters)
delivery.deliveryAddress.city*	string	City (2-50 characters)
delivery.deliveryAddress.state*	string	State (2 letters). Ex: SP
delivery.deliveryAddress.country*	string	Country (2 letters). Ex: BR
delivery.deliveryAddress.coordinates.latitude*	float	Latitude
delivery.deliveryAddress.coordinates.longitude*	float	Longitude

Items

Field	Type	Description
items[].id*	uuid	Item ID
items[].name*	string	Name (max. 50 characters)
items[].externalCode	string	External code
items[].quantity*	integer	Quantity (> 0)
items[].unitPrice*	float	Unit price (≥ 0)
items[].price*	float	Total price (quantity * unitPrice)
items[].optionsPrice*	float	Options price (≥ 0)
items[].totalPrice*	float	Total (price + optionsPrice)

Payments

Offline Payment:

Field	Type	Description
payments.methods[].method*	string	CREDIT, DEBIT or CASH
payments.methods[].type*	string	OFFLINE
payments.methods[].value*	float	Value
payments.methods[].card.brand*	string	Brand (if CREDIT/DEBIT)
payments.methods[].cash.changeFor*	float	Change (if CASH)

Online Payment: Do not send payments object (processed by merchant)

Other fields

Field	Type	Description
displayId	string	Friendly ID (max. 4 characters). Ex: A4BC
metadata	object	Additional information (max. 20 characters)

Preparation time

Use delivery.preparationTime to delay driver allocation.

Not sent: Immediate allocation
Sent: Allocation after specified time (in seconds)

Provide the most accurate time possible. Incorrect times may result in:

Delivery delays
Poor customer experience
Possible closure due to driver accumulation

Success response - 202 Accepted

{
  "id": "522e4d7e-0ce1-44f3-8cc7-73a9f190a5e8",
  "trackingUrl": "https://meupedido.ifood.com.br/522e4d7e-0ce1-44f3-8cc7-73a9f190a5e8"
}

Polling integration

Orders are available in event polling
Identified by salesChannel="POS"
Tracking available via tracking endpoint

Errors - 400 Bad Request

Code	Description
BadRequest	Request problem
BadRequestCustomer	Customer unavailable
BadRequestMerchant	Merchant unavailable
DeliveryDistanceTooHigh	Outside coverage area
HighDemand	Logistics temporarily unavailable
MerchantEasyDeliveryDisabled	Service not enabled
OffOpeningHours	Outside operating hours
OriginNotFound	Store outside logistics area
PaymentMethodNotFound	Payment method not found
PaymentTotalInvalid	Payment value does not match total
ServiceAreaMismatch	Address outside coverage
NRELimitExceeded	Driver limit reached

3. Address confirmation/change

Allows customer to confirm or request address change after order creation.

Available flows

With iFood tracking page

Customer uses iFood page to confirm/change address.Requirements:

Order CANNOT have customer.phone.type="STORE"
Valid phone is required for OTP

ImportantSend the correct phone used as WhatsApp to receive the OTP confirmation code.

Without iFood tracking page

Merchant implements own experience using endpoints.Note: iFood will not send OTP. Validation is merchant's responsibility.

3.1 Confirm address

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

Response: 202 Accepted
Event: DELIVERY_ADDRESS_CHANGE_USER_CONFIRMED

3.2 Request change

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

Required parameters:

streetName, neighborhood, city, state, country
coordinates (latitude, longitude)

Response deadlineMerchant has 15 minutes to accept/reject. After that, automatic rejection.

Limit: Maximum change of 500m from original coordinateEvent: DELIVERY_ADDRESS_CHANGE_REQUESTED

3.3 Accept change

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

Event: DELIVERY_ADDRESS_CHANGE_ACCEPTEDRegionMismatch Error: Generates automatic DELIVERY_ADDRESS_CHANGE_DENIED event with metadata.action="region-mismatch"

3.4 Reject change

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

Event: DELIVERY_ADDRESS_CHANGE_DENIED

Common errors

Code	Status	Description
BadRequest	400	Invalid parameters
OrderNotFound	404	Order not found or expired (>8h)
ChangeAddressOperationConflict	409	Conflict with existing operation
ChangeAddressOperationNotStarted	409	No pending change
MaxDistanceHigherThanAllowed	400	Change > 500m
RegionMismatch	400	New address in different region

4. Cancellation

Cancel orders with salesChannel="POS".

4.1 Get cancellation codes

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

Response 200 OK:

[{
  "cancelCodeId": "817",
  "description": "Customer cancelled order through restaurant"
}]

Response 204: Order can no longer be cancelled

4.2 Cancel order

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

Body:

{
  "reason": "Customer requested cancellation",
  "cancellationCode": "817"
}

Response: 202 AcceptedEvents:

CANCELLATION_REQUESTED
CANCELLED (success) or CANCELLATION_REQUEST_FAILED (failure)

5. Delivery trust level

Scoring system based on validation rules.

Available levels

Level	Description
LOW	Low trust
MODERATE	Moderate trust
HIGH	High trust
VERY_HIGH	Very high trust

Calculation rules

Rule	Description
customer_phone_valid	Valid phone (not STORE, >11 digits)
customer_phone_is_fixed	Landline phone (8 digits)
customer_address_confirmed	Address confirmed by customer
customer_address_change_requested	Customer requested change
merchant_address_change_approved	Merchant approved change
merchant_address_change_denied	Merchant denied change

Scoring examples

customer_phone_valid:false → LOW
customer_phone_is_fixed:true → MODERATE
customer_phone_is_fixed:true + customer_address_confirmed:true → VERY_HIGH
customer_phone_valid:true → HIGH
customer_phone_valid:true + approved change → VERY_HIGH
customer_phone_valid:true + denied change → LOW

Check level

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

Response 200 OK:

{
  "rules": {
    "customer_address_change_requested": false,
    "customer_address_confirmed": false,
    "customer_phone_is_fixed": false,
    "customer_phone_valid": true,
    "merchant_address_change_approved": false,
    "merchant_address_change_denied": false
  },
  "score": "HIGH"
}

Errors:

400 OrderWithoutSafeDelivery: Order without trust rules
404 OrderNotFound: Order not found

NoteThe score may change after order creation based on customer and merchant actions.

Next steps

Was this page helpful?

Rate your experience in the new Developer portal: