Search in documentation

Modules

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Solutions

Item

Exclusive module This module is exclusively for partners operating with marketplace channels and is not available to all developers. If you are interested in using functions from this API, contact the support team.

Overview

Use the Item API to send and manage products. iFood processes the data based on availability rules before displaying them in the app.

Integration strategy (POST vs PATCH)

WARNING: Use POST only to create items. Incorrect use for updates degrades integration performance.

To optimize performance, use the HTTP methods as described below:POST method (Creation):

Use ONLY to register new items or reactivate inactive items
Do not resend the complete catalog if there are no new products

PATCH method (Update):

Use to update existing items (price, inventory, details)
Send only the fields that have changed

Processing and volumetry limits

To ensure fast data ingestion and avoid processing queues, strictly follow the rule below:Golden rule: Plan the orchestration of shipments to not exceed 25% of the total catalog items in a 35-minute window.Impact: Compliance with this metric is essential to ensure performance stability and agility in data updates.Example: If the catalog has 10,000 items, send a maximum of 2,500 items every 35 minutes.Blocking: The API returns the 429 Too Many Requests status if the limit is exceeded. If you receive this error, wait for the next time window to begin.

Submission methods

1. Complete submission (POST)

Use strictly for new products.POST ingestion/{merchantId}?reset=falseRequired fields:

barcode: EAN (European Article Number) or internal scale code
name: Product name

Behavior:

null values overwrite existing data
The reset=true parameter deactivates products absent from the payload (destructive action)
Fields not sent will receive default values (null, empty string, 0, etc.)

NOTE: If the active and prices.price fields are not sent, they will receive the default values false and 0, respectively. This will cause the item to not be available in the catalog.

1.1. Reset parameter

When you send reset=true, iFood automatically deactivates all products absent from the payload.

WARNING: This action is destructive.

When to use:

Clean test products from the database
Remove improperly integrated items

Behavior: If no product is identified for deactivation, the process will not be executed.Payload example:

[
    {
        "barcode": "123",
        "name": "Produto de exemplo",
        "plu": null,
        "active": true,
        "inventory": {
            "stock": 1.5
        },
        "details": {
            "categorization": {
                "department": null,
                "category": null,
                "subCategory": null
            },
            "brand": null,
            "unit": null,
            "volume": null,
            "imageUrl": null,
            "description": null,
            "nearExpiration": true,
            "family": null
        },
        "prices": {
            "price": 0,
            "promotionPrice": null
        },
        "scalePrices": null,
        "multiple": null,
        "channels": null
    }
]

Important: For products sold by weight, the inventory.stock field must be informed in kilograms (KG). Example: 1 = 1 KG, 1.5 = 1.5 KG.

2. Partial submission (PATCH)

Recommended for catalog updates (price, inventory).PATCH ingestion/{merchantId}How it works:

Send only the modified fields

Payload example:The payload is the same as POST, the difference is that you will only send the fields you want to change.

[
    {
        "barcode": "123",
        "name": "Changing example product name"
    }
]

2.1. Important considerations

Do not use PATCH to activate a product.To reactivate products, use the POST method. The system requires the full payload to validate the information.

API Endpoint Details

POST Item Integration

Description: Sends new product integrations, updates all product data, or reactivates them.cURL example:

curl -X POST "https://merchant-api.ifood.com.br/item/v1.0/ingestion/{merchantId}?reset=false" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "barcode": "7891234567890",
      "name": "Whole Milk 1L",
      "active": true,
      "inventory": {
        "stock": 100
      },
      "prices": {
        "price": 5.99
      }
    }
  ]'

Response codes:

202 Success: Request processed successfully
400 Bad Request: Request error (data validation)
429 Too Many Requests: Request limit exceeded
500 Server Error: Server error

Request fields:

Field	Type	Required	Description
barcode	string	Yes	EAN or internal scale code
name	string	Yes	Product name
plu	string	No	Internal PLU code
active	boolean	No	Defines whether the item is active for sale
details	object	No	Product details (categorization, brand, volume, unit, image, description)
prices	object	No	Object containing `price` and `promotionPrice`
scalePrices	array	No	Array with tiered pricing rules by quantity
inventory	object	No	Object containing `stock` (quantity in stock)
multiple	object	No	Object for configuring multiples (iFood Shop exclusive) with `originalEan` and `quantity`
channels	array	No	Sales channels: `ifood-app`, `ifood-shop`

PATCH Item Integration

Description: Partial update recommended if the product has been sent previously and not all fields require changes. Allows sending only the fields you want to update.cURL example:

curl -X PATCH "https://merchant-api.ifood.com.br/item/v1.0/ingestion/{merchantId}" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "barcode": "7891234567890",
      "prices": {
        "price": 6.50
      }
    }
  ]'

Response codes:

202 Success: Request processed successfully
400 Bad Request: Request error (data validation)
429 Too Many Requests: Request limit exceeded
500 Server Error: Server error

Request fields:

Field	Type	Required	Description
barcode	string	Yes	EAN or internal scale code (identifier)
name	string	No	Product name
plu	string	No	Internal PLU code
active	boolean	No	Defines whether the item is active for sale
details	object	No	Product details (categorization, brand, volume, unit, image, description)
prices	object	No	Object containing `price` and `promotionPrice`
scalePrices	array	No	Array with tiered pricing rules by quantity
inventory	object	No	Object containing `stock` (quantity in stock)
multiple	object	No	Object for configuring multiples with `originalEan` and `quantity`
channels	array	No	Sales channels: `ifood-app`, `ifood-shop`

Item purging

The system permanently removes items from the catalog that have not been updated for 15 days and meet one of the following conditions:

Inactive status (active: false)
Zero or negative price (prices.price ≤ 0)

WARNING: Purged items require complete re-registration via the POST method.

How to avoid item purging

Send an update before the 15-day deadline to:

Change the status to active (active: true)
Update the price to a valid value (greater than zero)
Modify any other item field

Monitor inactive items or items with zero price in the Partner Portal to prevent unplanned deletions.

Main fields

The table below lists the main fields for item integration:

Field	Description
barcode	EAN or internal scale code
name	Product name
plu	Internal PLU code
active	Sales status (`true`/`false`)
inventory.stock	Quantity in stock
prices.price	Base price
prices.promotionPrice	Promotional price
scalePrices	Quantity discount rules
channels	Sales channels (`ifood-app`, `ifood-shop`)

Minimum payload example:

[
  {
    "barcode": "7891234567890",
    "name": "Whole Milk 1L",
    "active": true,
    "inventory": {
      "stock": 100
    },
    "prices": {
      "price": 5.99
    }
  }
]

Promotions

Promotion rules

Immediate application: Promotions in this module do not use scheduling (start/end dates). The discount takes effect immediately after submission.Update: To change a promotional value, resend the item via PATCH with the new price.Removal: To end a promotion, send the promotional value fields as null.

Validation and impact

Verification: Confirm the discount application in the Catalog section of the Partner Portal.Order module: Received orders will automatically contain the final price with the applied discount (promotional or wholesale price).

'FROM-TO' mechanics

Configure promotional prices by sending the original value and the discounted value.How to configure:

prices.price: Original value ("FROM" price)
prices.promotionPrice: Promotional value ("TO" price)

Rules:

The discount must be greater than 5%
To remove the promotion, send prices.promotionPrice: null

Example:

[
  {
    "barcode": "7891234567890",
    "prices": {
      "price": 10.00,
      "promotionPrice": 8.50
    }
  }
]

Quantity discount

This feature allows you to apply discounts on the unit price of the product from the purchase of a minimum quantity.How to configure:

scalePrices[0].quantity: Minimum quantity to activate the discount
scalePrices[0].price: Unit value with discount applied

Example:

[
  {
    "barcode": "7891234567890",
    "prices": {
      "price": 10.00
    },
    "scalePrices": [
      {
        "quantity": 6,
        "price": 9.00
      }
    ]
  }
]

In this example, the customer pays $10.00 per unit for purchases up to 5 items, and $9.00 per unit from 6 items onwards.

Multiples (iFood Shop)

Use this mechanic to sell packages with multiple units (e.g., bundles) on the iFood Shop channel.

These fields are exclusive to iFood Shop.

Required fields:

multiple.originalEan: EAN of the unit product contained in the package
multiple.quantity: Number of units in the package (values ≤ 1 invalidate the integration)
barcode: Package EAN or store internal code
plu: Use the format code_quantity for internal control
- Example: For a package of 12 units, use 7896045506217_12 or 1234_12.

Payload example:

[
  {
    "barcode": "7891234567890",
    "plu": "7891234567890_12",
    "name": "Whole Milk 1L - Pack of 12 units",
    "multiple": {
      "originalEan": "7891234567891",
      "quantity": 12
    }
  }
]

Sales channels

Use the channels field to restrict item integration to specific contracted channels.Accepted values:

ifood-app
ifood-shop

If the channels field is omitted or sent as null, changes will be automatically applied to all channels configured for the partner.

Example - Restrict item to iFood Shop:

[
  {
    "barcode": "7891234567890",
    "name": "Shop exclusive product",
    "channels": ["ifood-shop"]
  }
]

Example - Make available on multiple channels:

[
  {
    "barcode": "7891234567890",
    "name": "Multi-channel product",
    "channels": ["ifood-app", "ifood-shop"]
  }
]

Legacy integration migration

SiteMercado Service API

For partners who already integrate their items through the SiteMercado Service API, the migration to the Merchant API brings many similarities that facilitate the integration change.

Field mapping

Service API field	Merchant API field
idLoja	`In URL: ingestion/{merchantId}`
codigoBarra	barcode
nome	name
plu	plu
ativo	active
quantidadeEstoqueAtual	inventory.stock
departamento	details.categorization.department
categoria	details.categorization.category
subcategoria	details.categorization.subCategory
marca	details.brand
unidade	details.unit
volume	details.volume
imageURL	details.imageUrl
descricao	details.description
validadeProxima	details.nearExpiration
valor	prices.price
valorPromocao	prices.promotionPrice
listaEscalaPreco.quantidade	scalePrices[0].quantity
quantidadeAtacado	scalePrices[0].quantity
listaEscalaPreco.preco	scalePrices[0].price
valorAtacado	scalePrices[0].price
multiploEanOriginal	multiple.originalEan
multiploQtd	multiple.quantity
`ADDED`	channels[*]
familia	`REMOVED`
caracteristicas	`REMOVED`
quantidadeEstoqueMinimo	`REMOVED`

Homologation criteria

Check the criteria to perform your homologation.

Was this page helpful?

Rate your experience in the new Developer portal: