> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# iFood as a data source
> Bring data from iFood to your Lakehouse.
iFood is the largest food and grocery delivery marketplace in Latin America. Through the iFood Merchant API, partner stores can read their sales, financial settlements, payment anticipations and customer reviews — the data behind how much each store sold, what iFood charged, when it paid out and how customers rated the orders.
## Before you start
Access to the iFood Merchant API is granted to an **application** registered in the [iFood Developer Portal](https://developer.ifood.com.br), not to a store directly. Two things must be in place before this source can extract anything:
1. **The application must be homologated by iFood.** Homologation is a review carried out by iFood's integration team and is required before an application can request access to production stores. It is only available for Professional (CNPJ) accounts.
2. **Each store must approve the application.** Once homologated, the application requests access to a store by ID or CNPJ, and the store owner approves it in the iFood Partner Portal.
After both steps, the application's **Client ID** and **Client Secret** are what you provide to Nekt.
Do not enable the Order or Events modules on the application used with Nekt. iFood expects integrations subscribed to those modules to poll every 30 seconds, and a store whose integration stops polling can be marked offline and stop receiving orders. This source never uses them — order data is read from the Financial module instead.
## 1. Add your iFood access
1. In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the iFood option from the list of connectors.
2. Click **Next** and you'll be prompted to add your access.
* **Client ID:** The Client ID of your application in the iFood Developer Portal. You'll find it in the credentials tab of the application.
* **Client Secret:** The Client Secret of the same application.
* **Start Date:** The date of the first record you want to sync. Sales, financial entries and reviews from this date onwards will be extracted.
* **Store IDs:** *(optional)* Restrict the extraction to specific iFood store IDs. Leave it empty to extract every store the application has access to.
* **Lookback days:** *(optional, default 7)* How many days before the last synced record to re-read on every run. Sales and financial entries keep changing after they are created — status changes, commissions, refunds and renegotiations land later — so this window is what keeps records that were already extracted up to date.
3. Click **Next**.
## 2. Select your iFood streams
1. The next step is letting us know which streams you want to bring. A stream is an entity and you can select the whole entity (meaning all available attributes will come in each table) or only a subset of them.
> Tip: The stream can be found more easily by typing its name.
2. Click **Next**.
## 3. Configure your iFood data streams
1. Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a name for each table (which will effectively contain the fetched data) and the type of sync.
* **Layer**: choose between the existing [layers](https://docs.nekt.com/get-started/core-concepts/catalog-layers) on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: depending on the data you are bringing to the lake, you can choose between INCREMENTAL and FULL\_TABLE. Read more about Sync Types [here](https://docs.nekt.com/get-started/core-concepts/types-of-sync).
2. Click **Next**.
## 4. Configure your iFood data source
1. Describe your data source for easy identification within your organization. You can inform things like what data it brings, to which team it belongs, etc.
2. To define your [Trigger](https://docs.nekt.com/get-started/core-concepts/triggers), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).
3. Optionally, you can define some additional settings (if available).
* Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.
### Check your new source!
1. Click **Next** to finalize the setup. Once completed, you'll receive confirmation that your new source is set up!
2. You can view your new source on the [Sources](https://app.nekt.ai/sources) page. Now, for you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you have to wait for the pipeline to run. You can now monitor it on the [Sources](https://app.nekt.ai/sources) page to see its execution and completion. If needed, manually trigger the pipeline by clicking on the refresh icon. Once executed, your new table will appear in the Catalog section.
> If you encounter any issues, reach out to us via Slack, and we'll gladly assist you!
## Good to know
* **Orders come through the `Sales` stream.** iFood's order module is built for point-of-sale integrations: it delivers orders through a queue of events that must be consumed and acknowledged, and keeps order details for only 7 days. Reading it would interfere with the store's own POS integration, so this source reads orders from the Financial module's Sales API, which can be queried by date range as many times as needed.
* **Order items are not available.** No iFood bulk-read endpoint exposes the item-by-item content of an order. The `Sales` stream carries each order with its aggregate values (bag, delivery fee, service fee), payments, benefits, billing entries and status history — but not the individual products.
* **Anticipations only exist for some stores.** The `Anticipations` stream returns data only for stores with a payment anticipation plan (D+1 or D+7) through the iFood digital account. For every other store the table stays empty; the extraction is not affected.
* **Money fields follow the API.** iFood returns most monetary values as text in the Sales and Financial Events endpoints, so those columns land as strings and should be cast in your queries.
# Streams and Fields
Below you'll find all available data streams from iFood and their corresponding fields:
All stores the application has access to. Useful as the reference list of store IDs used by every other stream.
**Key Fields:**
* `id` - Unique identifier (UUID) of the store on iFood
* `name` - Public name of the store, as shown to customers
* `corporate_name` - Legal (corporate) name of the company that owns the store
Full profile of each store: registration data, address and enabled operations.
**Key Fields:**
* `id` - Unique identifier (UUID) of the store on iFood
* `name` - Public name of the store
* `corporate_name` - Legal name of the company that owns the store
* `description` - Free-text description registered on iFood
* `average_ticket` - Average order value of the store, as calculated by iFood
* `exclusive` - Whether the store sells exclusively through iFood
* `type` - Type of the store (RESTAURANT, STORE, GROUP)
* `status` - Registration status (AVAILABLE, UNAVAILABLE, DISABLED)
* `created_at` - When the store was created on iFood
**Address:**
* `address_country`, `address_state`, `address_city` - Location of the store
* `address_postal_code`, `address_district`, `address_street`, `address_number` - Full address
* `address_latitude`, `address_longitude` - Geographic coordinates
**Operations:**
* `operations` - Operations enabled for the store (delivery, indoor) and their sales channels, as a JSON object
Every sale made by each store, with the values, payments and status history behind it. This is the order-level stream.
**Key Fields:**
* `id` - Unique identifier (UUID) of the sale
* `short_id` - Short order number shown to the store and the customer
* `created_at` - When the sale was created (incremental replication key)
* `type` - Type of the sale
* `category` - Business category of the sale (for example FOOD or GROCERY)
* `sales_channel` - Channel the sale came through (for example IFOOD or POS)
* `current_status` - Current status of the sale (for example CONCLUDED or CANCELLED)
**Store:**
* `merchant_id`, `merchant_short_id`, `merchant_name`, `merchant_type` - Store that made the sale
* `merchant_timezone` - Timezone the sale timestamps refer to
* `merchant_documents` - Legal documents (CNPJ and others) of the store, as a JSON array
**Values:**
* `sale_gross_value_bag` - Gross value of the items in the order bag, before discounts
* `sale_gross_value_delivery_fee` - Delivery fee charged on the sale
* `sale_gross_value_service_fee` - Service fee charged on the sale
* `benefits_total_value` - Total value of all discounts and benefits applied
* `benefits` - Discounts and benefits with their target and sponsors, as a JSON array
**Delivery:**
* `delivery_type` - Type of delivery (for example DELIVERY or TAKEOUT)
* `delivery_information_provider` - Party that provided the delivery information
* `delivery_logistic_provider` - Logistics provider responsible for the delivery
* `delivery_product` - Delivery product used by iFood
* `delivery_code` - Internal code of the delivery arrangement
* `delivery_scheduling_type` - Whether the delivery was immediate or scheduled
* `delivery_gross_value`, `delivery_discount`, `delivery_net_value` - Delivery pricing
**Payments and billing:**
* `payments` - Payment methods used, with brand, wallet, liability and installments, as a JSON array
* `billing_summary_sale_balance` - Net balance of the sale for the store
* `billing_entries` - Commissions, fees and credits that compose the sale balance, as a JSON array
* `order_status_history` - Chronological history of the order status changes, as a JSON array
* `order_events` - Financial and operational events generated by the order, as a JSON array
The individual credits and debits registered against each store — the ledger behind every payout. Entries are recorded in the week they happen, not the week of the original sale, so a single order can produce entries across several settlement periods.
**Key Fields:**
* `merchant_id` - Store the entry belongs to
* `name` - Type of the financial event (for example ORDER\_COMMISSION or IFOOD\_SUBSIDY)
* `description` - Human readable description of the event
* `product` - iFood product the event relates to
* `trigger` - What triggered the event (for example SALE\_CONCLUDED)
* `date_time` - When the event was registered (incremental replication key)
* `competence` - Accounting month the event belongs to, in yyyy-MM format
* `has_transfer_impact` - Whether the entry changes the amount iFood transfers to the store; entries without impact are informational only
**Values:**
* `amount_value` - Monetary value of the entry, negative when it is a debit
* `billing_base_value` - Base value the fee was calculated on, when applicable
* `billing_fee_percentage` - Percentage applied over the base value, when applicable
* `settlement_expected_date` - Date the entry is expected to be settled with the store
**References:**
* `period_begin_date`, `period_end_date` - Calculation period the event falls into
* `reference_type` - Type of the record the event refers to, usually an order
* `reference_id` - Identifier of the record the event refers to; empty when the event is not tied to one
* `reference_date` - Date of the record the event refers to
* `receiver_business_id`, `receiver_business_type`, `receiver_business_document` - Business that receives the amount
* `payment_method`, `payment_brand`, `payment_liability` - Payment associated with the entry
The weekly settlement periods and the transfers that closed them — what iFood actually paid the store. One record per calculation period per store.
**Key Fields:**
* `merchant_id` - Store the settlement belongs to
* `start_date_calculation` - First day of the period the settlement was calculated over
* `end_date_calculation` - Last day of that period (incremental replication key)
* `balance` - Net amount received by the store across the queried window
* `query_begin_date`, `query_end_date` - Window that was queried to obtain the record
* `consolidated_merchants` - Stores consolidated into this settlement when the payout is grouped, as a JSON array
* `closing_items` - Individual closing items of the period — transfer, bank slip, renegotiation or receivable record — with amount, status, payment date and bank account details, as a JSON array
Payment anticipations (D+1 or D+7) contracted through the iFood digital account. Only returns data for stores that have an anticipation plan.
**Key Fields:**
* `merchant_id` - Store the anticipation belongs to
* `start_date_calculation` - First day of the period the anticipation was calculated over
* `end_date_calculation` - Last day of that period (incremental replication key)
* `balance` - Total amount anticipated to the store across the queried window
* `query_begin_date`, `query_end_date` - Window that was queried to obtain the record
* `consolidated_merchants` - Stores consolidated into this anticipation when the payout is grouped, as a JSON array
* `closing_items` - Individual anticipation items with the original amount, the fee percentage and value, the anticipated amount, the status and the original and anticipated payment dates, as a JSON array
Reviews customers left for each store, together with the replies the store posted.
**Key Fields:**
* `id` - Unique identifier (UUID) of the review
* `merchant_id` - Store the review refers to
* `score` - Rating the customer gave the order
* `previous_score` - Rating the customer had given before changing the review
* `has_score_changed` - Whether the customer changed the rating after submitting it
* `status` - Status of the review (CREATED, NOT\_REPLIED, REPLIED, PUBLISHED, INVALID, DISCARDED, UNKNOWN)
* `comment` - Free-text comment the customer wrote about the order
* `visibility` - Whether the review is public or private
* `version` - Version of the review record
* `survey_id` - Survey version the review answered
* `created_at` - When the review was created (incremental replication key)
**Order:**
* `order_id` - Order the review refers to
* `order_short_id` - Short order number the review refers to
* `order_created_at` - When the reviewed order was created
**Replies:**
* `replies` - Replies posted to the review, with their author and timestamp, as a JSON array