Search in documentation

Modules

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Solutions

Order

Overview

The API is event-driven. Events represent relevant actions or changes in the system, such as creating, updating the status, or completing an order. In an event-driven architecture, systems publish and consume events in a decoupled manner, which increases the scalability, flexibility, and resilience of the solution.

Event Delivery Methods

Delivery methods determine how iFood sends events to integrations. Each method defines how systems receive notifications about changes, such as order creation or updates.Currently, the order events module offers two delivery methods for integrators:

Polling

The integration periodically queries the iFood API for new events.

Webhook

iFood automatically sends events to an endpoint configured by the integration as soon as they occur.

Event Structure

Name	Description
`id`	Unique event ID
`code`	Event code
`fullCode`	Full event code (name)
`orderId`	Order to which this event is linked
`merchantId`	Merchant ID of the order
`createdAt`	Event creation date
`salesChannel`	Sales channel through which the order enters the platform (new channels can be added). Possible values: IFOOD, DIGITAL_CATALOG, POS, ECONOMIC, TOTEM, IFOOD_SHOP, IFOOD_APP, IFOOD_SITE, WAITER, POS, QR_CODE, IFOOD_SHOP_APP, IFOOD_SHOP_SITE, GROCERY_WHITELABEL_SITE
metadata	additional event information

Exemplo

{
  "id": "b03392c5-61dd-47c4-a503-bce3109c96c8",
  "code": "CFM",
  "fullCode": "CONFIRMED",
  "orderId": "93ba4bf4-f4ae-4de8-8017-35d7c7de9bf1",
  "merchantId": "820af392-002c-47b1-bfae-d7ef31743c99",
  "createdAt": "2021-02-17T19:36:55.295Z",
  "salesChannel": "IFOOD",
  "metadata": {
    "CLIENT_ID": "3c587f8f-fb22-46a7-88f8-781246a3ea3f"
  }
}

Event Groups

Order events can be classified by group:

Group	Description
`ORDER_STATUS`	Events representing a change in order status
`CANCELLATION_REQUEST`	Events related to order cancellation
`ORDER_TAKEOUT`	Events related to order pickup
`DELIVERY`	Events related to order delivery
`DELIVERY_ADDRESS`	Events related to changes in an order's delivery address
`DELIVERY_GROUP`	Events related to order delivery grouping
`DELIVERY_ONDEMAND`	Events related to iFood on-demand delivery service requests (hybrid or marketplace model)
`DELIVERY_COMPLEMENT`	Events related to complementary delivery (when the delivered order is incomplete)
`ORDER_HANDSHAKE`	Events related to the trading platform

Some events are optional. You don't need to implement them in your application. Even if you ignore these events, send the acknowledgment to prevent them from being resent in future polling requests.

Events by Group

ORDER_STATUS

Name	Code	Description
`PLACED`	PLC	New order on the platform
`CONFIRMED`	CFM	Order has been confirmed and will be prepared
`SEPARATION_STARTED`	SPS	Indicates the start of the order item separation process (Exclusive to Market orders)
`SEPARATION_ENDED`	SPE	Indicates the completion of the order item separation (Exclusive to Market orders)
`READY_TO_PICKUP`	RTP	Indicates that the order is ready for pickup (by the customer or the delivery person)
`DISPATCHED`	DSP	Indicates that the order is out for delivery
`CONCLUDED`	CON	Order completed
`CANCELLED`	CAN	Order canceled

iFood generates the CONCLUDED event automatically. The generation time can vary between the time of delivery and up to two hours later.

Exemplos

{
  "id": "58c3f8fc-fb2a-49a3-b99c-09ecf2cd590d",
  "code": "PLC",
  "fullCode": "PLACED",
  "orderId": "8ee1ba27-b3be-4164-8f5c-285236a20ecc",
  "merchantId": "820af392-002c-47b1-bfae-d7ef31743c99",
  "createdAt": "2021-02-17T15:07:20.04Z",
  "salesChannel": "IFOOD"
}

CANCELLATION_REQUEST

Name	Code	Description
`CANCELLATION_REQUESTED`	CAR	Cancellation request made by the Merchant (store) or iFood automatically (orders not confirmed within the deadline) or manually through our customer service team
`CANCELLATION_REQUEST_FAILED`	CARF	Cancellation request denied
`CONSUMER_CANCELLATION_REQUESTED`	CCR	Cancellation request made by the customer
`CONSUMER_CANCELLATION_ACCEPTED`	CCA	The cancellation request made by the customer was approved by the Merchant (store)
`CONSUMER_CANCELLATION_DENIED`	CCD	The cancellation request made by the customer was denied by the Merchant (store)

Whenever a cancellation request is approved, a CANCELLED (CAN) event is also generated.

Exemplos

{
  "id": "4d063d88-32f6-4b89-b68b-48890b098c71",
  "orderId": "dd2796df-1c09-446b-a3b4-81f28849c459",
  "merchantId": "820af392-002c-47b1-bfae-d7ef31743c99",
  "code": "CAR",
  "fullCode": "CANCELLATION_REQUESTED",
  "createdAt": "2021-02-17T19:51:45.704Z",
  "salesChannel": "IFOOD",
  "metadata": {
    "reason_code": "504",
    "details": "MANUAL(RESTAURANT_WITHOUT_DELIVERY_MAN) - Restaurante sem entregador",
    "ORIGIN": "ORDER_MANAGER",
    "CLIENT_ID": "iconnect_v3_homologation"
  }
}

HANDSHAKE_PLATFORM

Name	Code	Description
`HANDSHAKE_DISPUTE`	HSD	The event indicates that a negotiation has been initiated and must be responded to
`HANDSHAKE_SETTLEMENT`	HSS	The event signals and formalizes that a negotiation has been responded to

Examples

{
  "id": "6d34f8be-7fa6-40f1-877f-8ac564db2a7c",
  "orderId": "23f5d785-6c76-47d8-bdd0-b3090c90a2a8",
  "code": "HSD",
  "fullcode": "HANDSHAKE_DISPUTE",
  "merchantId": "23f5d785-6c76-47d8-bdd0-b3090c90a2a8",
  "createdAt": "2023-06-23T13:09:06.287636Z",
  "salesChannel": "IFOOD",
  "metadata": {
    "disputeId": "5166ded9-bdee-4440-8c73-b5488e8b1f83",
    "action": "CANCELLATION",
    "timeoutAction": "REJECT_CANCELLATION",
    "handshakeType": "AFTER_DELIVERY",
    "handshakeGroup": "CUSTOMER_ORDER_SUPPORT",
    "message": "Pedido veio errado",
    "expiresAt": "2023-06-23T13:15:06.287636Z",
    "alternatives": [
      {
        "id": "2d35d0b9-67ae-46d2-8261-f0a40e5d07fd",
        "type": "REFUND",
        "metadata": {
          "maxAmount": {
            "value": "6000",
            "currency": "BRL"
          }
        }
      }
    ],
    "metadata": {
      "evidences": [
        {
          "url": "https://merchant-api.ifood.com.br/notification/v1.0/orders/{orderId}/assets/{imageId}",
          "contentType": "image/jpg"
        }
      ],
      "items": [
        {
          "id": "296b1757-4edf-4a4a-9f03-dfc10d4e907a",
          "uniqueId": "fe3620ad-c475-4f01-93b9-1ed95907a9ab",
          "integrationId": "73",
          "index": 1,
          "quantity": 1,
          "amount": {
            "value": "3890",
            "currency": "BRL"
          },
          "reason": "Não veio a batata, apenas as esfihas"
        }
      ],
      "garnishItems": [
        {
          "id": "ffa2e2f0-361e-4076-8781-e7c8073326e1",
          "parentUniqueId": "efe73d06-ccfd-4605-a2a5-1b5b64284b47",
          "integrationId": "MAI-9601273-601273",
          "quantity": 1,
          "index": 2,
          "amount": {
            "value": "2650",
            "currency": "BRL"
          },
          "reason": "Revirado e faltando o queijo"
        }
      ]
    },
    "createdAt": "2023-06-23T13:06:50.448434Z"
  },
  "receivedAt": "2023-06-23T13:06:50.628451Z"
}

DELIVERY

Name	Code
`ASSIGN_DRIVER`	ADR
`GOING_TO_ORIGIN`	GTO
`ARRIVED_AT_ORIGIN`	AAO
`DELIVERY_DRIVER_DEALLOCATED`	DDD
`COLLECTED`	CLT
`ARRIVED_AT_DESTINATION`	AAD
`DELIVERY_RETURNING_TO_ORIGIN`	DRGO
`DELIVERY_RETURNED_TO_ORIGIN`	DRDO
`DELIVERY_CANCELLATION_REQUESTED`	DCR
`DELIVERY_DROP_CODE_REQUESTED`	DDCR
`DELIVERY_DROP_CODE_VALIDATION_SUCCESS`	DDCS
`DELIVERY_RETURN_CODE_REQUESTED`	DRCR
`DELIVERY_PICKUP_CODE_REQUESTED`	DPCR
`DELIVERY_PICKUP_CODE_VALIDATION_SUCCESS`	DPCS

Partner Delivery Orders

Partner delivery orders (deliveryBy: "IFOOD") can have multiple deliveries. This occurs, for example, if an item is missing from the order and a second delivery is required, or when a large order is split between multiple delivery drivers.Events include three metadata fields to identify the delivery type:

deliveryId: uniquely identifies each delivery and allows tracking of all steps, even for orders with multiple deliveries or repeating logistics events.
deliveryType: indicates whether the delivery is MAIN or COMPLEMENT.
deliveryComplementType: details the type of complementary delivery — HUGE_ORDER for large orders split between deliveries or MISSING_ITEM for missing items. Supplementary deliveries are exclusive to orders placed through iFood.

For On-Demand orders (salesChannel: "POS"), DELIVERY_DROP_CODE events include the code field in the metadata. For Full-Service orders (salesChannel: "IFOOD"), these events do not include the code field.

Exemplos

{
  "id": "4d063d88-32f6-4b89-b68b-48890b098c71",
  "orderId": "dd2796df-1c09-446b-a3b4-81f28849c459",
  "merchantId": "820af392-002c-47b1-bfae-d7ef31743c99",
  "code": "ADR",
  "fullCode": "ASSIGN_DRIVER",
  "createdAt": "2021-02-17T19:51:45.704Z",
  "salesChannel": "IFOOD",
  "metadata": {
    "deliveryId": "b0954b6b-f99c-44b6-ba1e-987f32b2b22a",
    "deliveryType": "MAIN",
    "workerVehicleType": "CAR",
    "workerName": "Fulano da Silva",
    "workerExternalUuid": "99d1d32e-7001-4b94-b969-17366d40159b",
    "workerPhotoUrl": "https://nv-production-logistics-driver-account.s3.amazonaws.com/static/drivers/photo/99d1d32e-7001-4b94-b969-17366d401999.jpg"
  }
}

DELIVERY_ADDRESS

DELIVERY_ADDRESS events are exclusive to On-Demand orders (salesChannel:"POS").

Name	Code	Description
`DELIVERY_ADDRESS_CHANGE_REQUESTED`	DAR	Customer requested a change to the order's shipping address
`DELIVERY_ADDRESS_CHANGE_USER_CONFIRMED`	DAU	Customer confirmed the shipping address
`DELIVERY_ADDRESS_CHANGE_ACCEPTED`	DAA	The shipping address change was approved by the partner
`DELIVERY_ADDRESS_CHANGE_DENIED`	DAD	The shipping address change was denied by the partner

Examples

{
  "id": "4d063d88-32f6-4b89-b68b-48890b098c71",
  "orderId": "dd2796df-1c09-446b-a3b4-81f28849c459",
  "merchantId": "820af392-002c-47b1-bfae-d7ef31743c99",
  "code": "DAR",
  "fullCode": "DELIVERY_ADDRESS_CHANGE_REQUESTED",
  "createdAt": "2021-02-17T19:51:45.704Z",
  "salesChannel": "IFOOD",
  "metadata": {
    "address": {
      "streetName": "Rua de teste",
      "streetNumber": "1",
      "complement": "Teste",
      "reference": "Teste",
      "neighborhood": "Centro",
      "city": "Bairro de Teste",
      "state": "AC",
      "country": "BR",
      "coordinates": {
        "latitude": -9.11,
        "longitude": -67.22
      }
    }
  }
}

DELIVERY_GROUP

When orders are grouped for delivery, the DELIVERY_GROUP_ASSIGNED event is generated. The event metadata contains the complete list of grouped orderIds. To avoid duplication, the event is sent only for the first order in the list. To query information for another order in the group, use the main order event.Starting September 12, 2025, the events will be migrated and will follow the new behavior described below:When an order is associated with a delivery group, that is, with a route with multiple orders, the following event will be published: DELIVERY_GROUP_ASSOCIATED. The event metadata contains the complete list of grouped orderIds. When an order is disassociated from a delivery group, the following event will be published: DELIVERY_GROUP_DISSOCIATED. When there is a change in the delivery group (associating and dissociating an order from the delivery group), the DELIVERY_GROUP_UPDATED event will be issued only for orders that were already part of the group and remain in the group after the change. Orders being added to the group will receive DELIVERY_GROUP_ASSOCIATED, and orders being removed will receive DELIVERY_GROUP_DISSOCIATED.

Name	Code	Description
`DELIVERY_GROUP_ASSIGNED`	DGA	Indicates that two or more orders were grouped into the same delivery route
`DELIVERY_GROUP_DISMISSED`	DGD	Indicates that the delivery route for grouped orders has been removed
`DELIVERY_GROUP_ASSOCIATED`	DGAC	Indicates that the order has been associated with a delivery group, i.e., a route with multiple orders
`DELIVERY_GROUP_DISSOCIATED`	DGDC	Indicates that the order has been disassociated from the delivery group
`DELIVERY_GROUP_UPDATED`	DGU	Indicates that there has been a change in the delivery group

Attention The DELIVERY_GROUP_ASSOCIATED, DELIVERY_GROUP_DISSOCIATED, and DELIVERY_GROUP_UPDATED events will be published on September 12, 2025, and will replace the previous events.The DELIVERY_GROUP_ASSIGNED and DELIVERY_GROUP_DISMISSED events will be discontinued on October 13, 2025.

Examples

{
  "id": "4d063d88–32f6–4b89-b68b-48890b098c71",
  "orderId": "dd2796df-1c09–446b-a3b4–81f28849c459",
  "merchantId": "820af392–002c-47b1-bfae-d7ef31743c99",
  "code": "DGAC",
  "fullCode": "DELIVERY_GROUP_ASSOCIATED",
  "createdAt": "2025–08–17T19:51:45.704Z",
  "salesChannel": "IFOOD",
  "metadata": {
    "deliveryGroupId": "4d063d88–32f6–4b89-b68b-48890b098c71",
    "orderIds": [
      "849516e1–1493–40d9–82a0–49640dc09311",
      "a874d6c2–0a57–447a-b8a0-c0080299f158",
      "ece9e2a1-da09–47f8–9e85-ee7828d2a31f"
    ]
  }
}

DELIVERY_ONDEMAND

Name	Code	Description
`REQUEST_DRIVER`	RDR	Indicates that a request for the on-demand delivery service was made
`REQUEST_DRIVER_SUCCESS`	RDS	Delivery request approved
`REQUEST_DRIVER_FAILED`	RDF	Delivery request denied Possible values: SAFE_MODE_ON, OFF_WORKING_SHIFT_POST, CLOSED_REGION, SATURATED_REGION
`DELIVERY_CANCELLATION_REQUEST_ACCEPTED`	DCRA	The delivery person cancellation request was successful
`DELIVERY_CANCELLATION_REQUEST_REJECTED`	DCRR	The delivery person cancellation request was not successful

Examples

{
  "id": "4d063d88-32f6-4b89-b68b-48890b098c71",
  "orderId": "dd2796df-1c09-446b-a3b4-81f28849c459",
  "merchantId": "820af392-002c-47b1-bfae-d7ef31743c99",
  "code": "RDR",
  "fullCode": "REQUEST_DRIVER",
  "createdAt": "2021-02-17T19:51:45.704Z",
  "salesChannel": "IFOOD",
  "metadata": {
    "ORIGIN": "ORDER_MANAGER",
    "CLIENT_ID": "iconnect_v3_homologation"
  }
}

DELIVERY_COMPLEMENT

Name	Code	Description
`RETURN_TO_STORE`	RTS	Return request to retrieve missing order items (complement an incompletely delivered order)

Example

{
  "id": "05dec672-5fd7-46ce-bdd2-fda515d33eb8",
  "code": "RTS",
  "fullCode": "RETURN_TO_STORE",
  "orderId": "96eebd06-50a5-4e87-908d-d93bbb1ef17b",
  "merchantId": "820af392-002c-47b1-bfae-d7ef31743c99",
  "createdAt": "2021-02-23T15:28:13.084Z",
  "salesChannel": "IFOOD"
}

OTHER

It is not possible to filter events in the OTHER group.

Name	Code	Description
`ORDER_PATCHED`	OPA	Indicates that there was a change to the order
`RECOMMENDED_PREPARATION_START`	RPS	Recommendation to start order preparation to optimize pickup and delivery. Generated only for orders with iFood delivery and when our algorithms identify an opportunity to optimize the start of preparation.
`PREPARATION_STARTED`	PRS	Order started to be prepared
`CONSUMER_PREPARATION_TIME_REQUESTED`	CPR	Customer requests information about the order preparation time
`CHANGE_PREPARATION_TIME`	CPT	Informs the customer that there was a change in the order preparation time
`BOX_ASSIGNED`	BOA	Order eligible for delivery to iFood Box
`READY_FOR_INVOICE`	RFI	Order eligible for invoice generation and printing

Examples

{
  "id": "4d063d88-32f6-4b89-b68b-48890b098c71",
  "orderId": "dd2796df-1c09-446b-a3b4-81f28849c459",
  "merchantId": "820af392-002c-47b1-bfae-d7ef31743c99",
  "code": "OPA",
  "fullCode": "ORDER_PATCHED",
  "createdAt": "2021-02-23T11:51:45.704Z",
  "salesChannel": "IFOOD",
  "metadata": {
    "changes": [
      {
        "changeType": "EDIT_ITEMS",
        "items": [
          {
            "id": "3dc09021-be6b-4be6-92a1-15a07b464141",
            "uniqueId": "3dc09021-be6b-4be6-92a1-15a07b464141",
            "externalCode": "123",
            "changes": {
              "optionsChanges": [
                {
                  "changeType": "ADD_OPTIONS",
                  "options": [
                    {
                      "id": "d585214c-b95a-4c4d-9d05-16f7d8f99999",
                      "externalCode": "1234567",
                      "quantity": 1,
                      "unitPrice": 2
                    }
                  ]
                },
                {
                  "changeType": "EDIT_OPTIONS",
                  "options": [
                    {
                      "id": "d585214c-b95a-4c4d-9d05-16f7d8f98799",
                      "quantity": {
                        "from": 2,
                        "to": 1
                      },
                      "unitPrice": 7
                    }
                  ]
                },
                {
                  "changeType": "DELETE_OPTIONS",
                  "options": [
                    {
                      "id": "d585214c-b95a-4c4d-9d05-16f7d8f98789"
                    }
                  ]
                }
              ],
              "quantity": {
                "from": "1",
                "to": "800"
              },
              "unit": {
                "from": "KG",
                "to": "g"
              }
            },
            "unitPrice": 20,
            "optionsPrice": {
              "from": 8.5,
              "to": 2
            },
            "totalPrice": {
              "from": 28.5,
              "to": 22
            }
          }
        ]
      }
    ],
    "total": {
      "subtotal": {
        "from": 28.5,
        "to": 22
      }
    },
    "payments": {
      "methods": [
        {
          "value": 22,
          "currency": "BRL",
          "type": "ONLINE",
          "method": "CREDIT / DEBIT / MEAL_VOUCHER / FOOD_VOUCHER",
          "card": {
            "brand": "Nome da Bandeira"
          }
        }
      ]
    }
  }
}

Was this page helpful?

Rate your experience in the new Developer portal: