Search in documentation
ctrl+4K
Modules
Authentication
Merchant
Catalog
Order
Events
Logistics
Shipping
Review
Financial
Solutions

Endpoints

Reference of Catalog API v2.0 endpoints.
Test in Postman
The pre-configured Postman collections cover all endpoints on this page.

Catalogs

List catalogs

Get all catalogs from the store and their contexts.
curl --request GET \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/catalogs' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Response:
[
  {
    "catalogId": "cat-main-001",
    "context": ["DEFAULT"],
    "status": "AVAILABLE",
    "modifiedAt": 1640000000.12345
  }
]

Categories

List categories

Get all categories. Use the include_items=true parameter to include items within each category.
curl --request GET \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/categories?include_items=true' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Create category

Create a category to group items.
curl --request POST \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/categories' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Sandwiches",
    "status": "AVAILABLE",
    "template": "DEFAULT"
  }'
Response:
{
  "id": "cat-lanches-001",
  "name": "Sandwiches",
  "status": "AVAILABLE",
  "template": "DEFAULT"
}

Items

Create or update item

Create a complete item with products, add-on groups, and options. If the IDs already exist, the API updates the item. Use contextModifiers to override price, status, or code per context.
curl --request PUT \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/items' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "item": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "DEFAULT",
      "categoryId": "cat-lanches-001",
      "status": "AVAILABLE",
      "price": {"value": 25.00},
      "externalCode": "BURGER_001",
      "contextModifiers": [
        {
          "catalogContext": "WHITELABEL",
          "price": {"value": 28.00},
          "status": "UNAVAILABLE"
        }
      ]
    },
    "products": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "X-Burger",
        "description": "Bread, meat, cheese and lettuce",
        "externalCode": "BURGER_PROD_001"
      }
    ],
    "optionGroups": [],
    "options": []
  }'

List items in category

Get the items of a category with their add-ons.
curl --request GET \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/categories/cat-lanches-001/items' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Get specific item

Get an item with all its components (product, groups, options).
curl --request GET \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/items/550e8400-e29b-41d4-a716-446655440000/flat' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

List sellable items

Get active and available items for sale in a catalog.
curl --request GET \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/catalogs/cat-main-001/sellableItems' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

List non-sellable items

Get blocked items and the reason for each. Use this endpoint to diagnose why an item does not appear in the app.Possible restrictions:
  • CATEGORY_PAUSED — Category paused.
  • ITEM_PAUSED — Item paused.
  • ITEM_PRICE_MISSING — Item without price.
  • OPTION_GROUP_WITHOUT_AVAILABLE_OPTIONS — Mandatory group without available options.
  • OPTION_PAUSED — Add-on paused.
curl --request GET \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/catalogs/cat-main-001/unsellableItems' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Update item price

Change the price of an item globally or per context.
curl --request PATCH \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/items/price' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "itemId": "550e8400-e29b-41d4-a716-446655440000",
    "price": {"value": 26.00},
    "priceByCatalog": [
      {
        "value": 29.00,
        "catalogContext": "WHITELABEL"
      }
    ]
  }'

Update item status

Pause or reactivate an item globally or per context.
curl --request PATCH \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/items/status' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "itemId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "AVAILABLE",
    "statusByCatalog": [
      {
        "status": "UNAVAILABLE",
        "catalogContext": "WHITELABEL"
      }
    ]
  }'

Update item external code

Change the POS code of an item globally or per context.
curl --request PATCH \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/items/externalCode' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "itemId": "550e8400-e29b-41d4-a716-446655440000",
    "externalCode": "BURGER_NEW_001",
    "externalCodeByCatalog": [
      {
        "externalCode": "BURGER_WL_001",
        "catalogContext": "WHITELABEL"
      }
    ]
  }'

Add-ons

Update add-on price

Change the price of an option globally or per context.
curl --request PATCH \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/options/price' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "optionId": "opt-coke-001",
    "price": {"value": 8.50},
    "priceByCatalog": [
      {
        "value": 9.00,
        "catalogContext": "WHITELABEL"
      }
    ]
  }'

Update add-on status

Pause or reactivate an add-on option.
curl --request PATCH \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/options/status' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "optionId": "opt-coke-001",
    "status": "UNAVAILABLE",
    "statusByCatalog": [
      {
        "status": "AVAILABLE",
        "catalogContext": "WHITELABEL"
      }
    ]
  }'

Update add-on external code

Change the POS code of an option.
curl --request PATCH \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/options/externalCode' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "optionId": "opt-coke-001",
    "externalCode": "COKE_NEW_001",
    "externalCodeByCatalog": [
      {
        "externalCode": "COKE_WL_001",
        "catalogContext": "WHITELABEL"
      }
    ]
  }'

Batch operations

Update prices in batch

Update prices for items and add-ons in batch. Use externalCode or productId to identify resources. Include catalogContext to update only a specific context.
curl --request PATCH \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/products/price' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "externalCode": "BURGER_001",
      "price": {"value": 27.00},
      "resources": ["ITEM"]
    }
  ]'
Response:
{
  "batchId": "batch-id-001",
  "url": "/v2.0/merchants/YOUR_MERCHANT_ID/batch/batch-id-001"
}

Update status in batch

Update status for items and add-ons in batch.
curl --request PATCH \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/products/status' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "externalCode": "BURGER_001",
      "status": "UNAVAILABLE",
      "resources": ["ITEM"]
    }
  ]'

Check batch operation status

Track the progress of a batch operation. Batch operations run asynchronously — check this endpoint until batchStatus is COMPLETED.
curl --request GET \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/batch/batch-id-001' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Response:
{
  "batchStatus": "COMPLETED",
  "results": [
    {
      "resourceId": "resource-id-001",
      "result": "SUCCESS"
    }
  ]
}

Inventory

Create inventory

Set the maximum sellable quantity of a product.
curl --request POST \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/inventory' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "productId": "prod-cake-001",
    "quantity": 10
  }'

Get inventory

Get the current inventory of a product.
curl --request GET \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/inventory/prod-cake-001' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Response:
{
  "productId": "prod-cake-001",
  "quantity": 8
}

Delete inventory

Remove the inventory limit from one or more products.
curl --request POST \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/inventory/batchDelete' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "productIds": ["prod-cake-001"]
  }'

Images

Image upload

Send an image in base64. Supported formats: jpg, jpeg, png. Maximum size: 5 MB.
curl --request POST \
  --url 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/YOUR_MERCHANT_ID/image/upload' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
  }'
Response:
{
  "imagePath": "merchant-id/202311161149_abc123.png"
}
You can reuse the imagePath across multiple items and products. PUT and POST endpoints also accept images in base64 directly in the payload.

Error handling

See Errors and troubleshooting for the complete reference of HTTP codes, diagnosis of common issues, and best practices.
Was this page helpful?
Rate your experience in the new Developer portal:
On this page
Endpoints
Catalogs
List catalogs
Categories
List categories
Create category
Items
Create or update item
List items in category
Get specific item
List sellable items
List non-sellable items
Update item price
Update item status
Update item external code
Add-ons
Update add-on price
Update add-on status
Update add-on external code
Batch operations
Update prices in batch
Update status in batch
Check batch operation status
Inventory
Create inventory
Get inventory
Delete inventory
Images
Image upload
Error handling
Content read0%