Search in documentation

Modules

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Solutions

Events

Overview

Polling is a simple method to receive updates from an API. Your system sends regular requests, every 30 seconds, to the GET /events:polling endpoint and checks if there are new events. The API returns new information since the last request.When there are events, the API returns code 200 with the list. If there are no events, it returns 204.Polling is easy to implement, but can increase traffic and cause delays compared to webhooks.

Event retention

The API maintains orders and events for up to 8 hours after delivery. After this period, the API does not return the events. The API only returns events without ACK. Send ACK only after ensuring you have stored the event.

Event ordering

The API may deliver events out of order. To ensure the correct sequence, sort events by the createdAt field after receiving them.

Filters

You can filter the orders received in polling.

Filter by category

Use the categories parameter in the query to filter orders by category. By default, the API returns events for FOOD and GROCERY categories. Check order categories for more details.

/events:polling?categories=FOOD,GROCERY,ANOTAI,FOOD_SELF_SERVICE 
/events:polling?categories=ALL (All categories will be returned, including new categories that will be created over time)

ANOTAI category orders only appear if the restaurant uses Pagamento Online iFood payment in Anota AI. Otherwise, these orders are not displayed.

Filter by event type

Use the types and groups parameters to filter events by type or group.Examples:

/events:polling?groups=STATUS,DELIVERY,TAKEOUT
/events:polling?types=COL,CFM,CAN,AAO
/events:polling?groups=ORDER_STATUS&types=AAO,AAD

Unfiltered events receive automatic acknowledgment (auto-acknowlegment). If you change the filter, already confirmed events will not be returned. Consume all events in a single flow and pass them according to your logic.The groups already include the types. Avoid duplicate filters, like ?groups=ORDER_STATUS&types=PLC,CFM....It's not possible to filter events from the OUTROS group. To receive all events, don't use filters.

Filter by merchants

The endpoint returns events from up to 500 stores that your token accesses. Use the x-polling-merchants header to specify stores.Example:

--header 'x-polling-merchants: 0a0000aa-0aa0-00aa-aa00-0000aa000001,0a0000aa-0aa0-00aa-aa00-0000aa000002,0a0000aa-0aa0-00aa-aa00-0000aa000003'

Filter x-pooling-merchants and centralized and distributed applications

If your application (centralized or distributed) uses a token with permission for multiple merchants, add the x-polling-merchants filter in polling requests. This way, you receive events only from the specified merchant. Without this filter, the system sends events from all merchants linked to the token.In centralized applications with tokens that access many merchants, always use the x-polling-merchants header to filter events by merchant. Otherwise, the error "Bad request. Too many polling merchants" may occur. In the header, send a list of IDs of the desired merchants. The limit is 100 IDs per header.If your application accesses up to 500 merchants and you don't use the header, it will receive events from all merchants. For access above 500 merchants, it's mandatory to use the header and divide requests into batches of up to 100 merchants each.

For centralized applications with more than 500 merchants, we recommend using webhooks. Webhooks deliver events in real time and reduce problems with using the x-polling-merchants filter.

403 - Forbidden

If you don't use the x-polling-merchants filter when making a polling request, the API will return events from all merchants that the token accesses.When you use the x-polling-merchants filter, the API checks if the token has permission for all informed merchants. If the token doesn't have permission for some merchant, the API returns error 403. The response body, in the unauthorizedMerchants field, lists merchants without permission.How to resolveRemove merchants without permission from the x-polling-merchants filter and send a new polling request to receive events from authorized merchants.How to identify the causeCheck if the merchant revoked access to your application. If necessary, request new authorization from the merchant's responsible party.If the merchant approved access recently, the token may have been generated before approval. Generate a new token to access the approved merchant.

Multiple devices or applications

More than one application can consume events from the same store. The API generates a unique identifier for each application based on credentials, called "device". Acknowledgment control uses this identifier.Another application may receive and confirm a PLACED type event before yours. In this situation, you will receive the confirmation event generated by another device. Record and update the order status based on all received events, even if they come from other devices.This mechanism allows the store to use different applications, like your app and Order Manager, at the same time.

Rate Limit Each client can make one request every 30 seconds per token. If you exceed this limit, the API may temporarily block the client and return code 429.

Order events

Learn more here about all details and examples of events sent by iFood.

Duplicate events and order date

The API may return the same event more than once, including old PLACED events. Always check the event ID and discard duplicates. Don't process the same event more than once.Perform acknowledgment for all received events, even if you have already processed them before.If you receive a repeated PLACED event, discard it and don't create a new order.

Event acknowledgment

Always send /acknowledgment when receiving new events to avoid receiving them again. In the request body, send an array with event IDs or the complete content received in polling. The API only uses the ID to process acknowledgment. Each request accepts up to 2000 IDs.Guidelines:

Send acknowledgment for each polling with events.
Send acknowledgment for all events, even those not used by your system.
Send acknowledgment only once per event.

Presence in polling

The merchant remains online while your integration performs event polling every 30 seconds. If polling stops, the merchant loses online status.

Learn more here about the concept of presence in iFood.

Homologation criteria

Check below the requirements and homologation criteria:

To perform application homologation, it must already be ready. Tests are done on the APP as a whole and not just on calls to our APIs.

Homologation requests with Personal/Student account registrations (CPF) will not be accepted. Only requests with Professional account registration (CNPJ).

Send requests to the GET /events:polling endpoint every 30 seconds to not lose orders.
Use the x-pooling-merchants header to filter events by merchant.
Also filter events by type and group, if necessary.
Send POST /events/acknowledgment for all received events (code 200) immediately after the polling request.
For Logistics Integrator applications, it's mandatory to send the excludeHeartbeat=true parameter when making a request to the GET /events:polling endpoint. This is necessary to prevent the store from being opened, causing order cancellation and subsequently preventing the merchant from being penalized on the platform for misuse of the module. Learn more in Status de Conexão dos Parceiros no iFood.

Was this page helpful?

Rate your experience in the new Developer portal:

On this page