Search in documentation

Modules

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Solutions

Using the API

Listing catalogs

The first step in catalog APIs is listing catalogs through the GET /merchants/{merchantId}/catalogs API. Currently we have DEFAULT and INDOOR catalogs, indicating that this catalog is for DeliveryRequest:

curl --location --request GET 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/catalogs' \
--header 'Authorization: Bearer TOKEN

Response

[
  {
    "catalogId": "10e0fbbe-7279-4ee3-9a2f-caf1f93f7b8e",
    "context": ["DEFAULT"],
    "status": "AVAILABLE",
    "modifiedAt": 1597350642.71608
  }
]

Listing categories

With the catalog id in hand, it's possible to list all categories and items of a catalog through the GET /merchants/{merchantId}/catalogs/{catalogId}/categories API.Request:

curl --location --request GET 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/catalogs/10e0fbbe-7279-4ee3-9a2f-caf1f93f7b8e/categories?include_items=true \
--header 'Authorization: Bearer TOKEN

Response:

[]

Since we haven't added anything to our catalog yet, it returns an empty list! Following the next steps you will learn how to build your catalogHere we have an example of the return from this endpoint with an item already created

[
  {
    "id": "a8533d43-aec8-467c-adf6-8a24791829a0",
    "name": "Burgers",
    "status": "AVAILABLE",
    "sequence": 0,
    "index": 0,
    "template": "DEFAULT",
    "items": [
      {
        "id": "16ae5fc9-7e34-4623-8a0c-722d12fd49e9",
        "name": "X-Burger",
        "description": "Bread, meat, cheese and salad",
        "externalCode": "xburguer_wl",
        "status": "AVAILABLE",
        "sequence": 0,
        "index": 0,
        "productId": "fdb50f52-7b62-46f7-a574-f3bc00c3f673",
        "imagePath": "",
        "price": {
          "value": 10,
          "originalValue": 15
        },
        "shifts": [
          {
            "startTime": "00:00",
            "endTime": "20:59",
            "monday": true,
            "tuesday": true,
            "wednesday": true,
            "thursday": true,
            "friday": true,
            "saturday": true,
            "sunday": true
          }
        ],
        "serving": "SERVES_2",
        "dietaryRestrictions": [
          
        ],
        "optionGroups": [
          {
            "id": "13736a09-ac48-4f8f-bcb1-56d6a5dcdf33",
            "name": "Sides",
            "min": 0,
            "max": 1,
            "sequence": 0,
            "index": 0,
            "status": "AVAILABLE",
            "options": [
              {
                "id": "105f9323-0afb-41a1-b8af-13851424c603",
                "name": "French Fries",
                "description": "200 g",
                "externalCode": "option_fritas_wl",
                "productId": "38cea6cb-19d5-42b4-87b9-f46c90e7bc1d",
                "status": "UNAVAILABLE",
                "sequence": 0,
                "index": 0,
                "price": {
                  "value": 20
                }
              },
              {
                "id": "78490bf7-a924-4eb2-94a3-4489eadd4f3c",
                "name": "Onion Rings",
                "description": "200 g",
                "externalCode": "option_onion_ring_wl",
                "productId": "0f309165-3c72-468c-bdf5-637b272bc09c",
                "status": "AVAILABLE",
                "sequence": 1,
                "index": 1,
                "price": {
                  "value": 3
                }
              }
            ]
          }
        ],
        "hasOptionGroups": true,
        "contextModifiers": [
            {
                "catalogContext": "WHITELABEL",
                "itemContextId": "83cd029d-d833-42dd-bbd6-017c12312968"
            },
            {
                "catalogContext": "DEFAULT",
                "itemContextId": "d2e6820e-cc5c-42e3-99db-c180c2bcf4ad"
            }
        ]
      }
    ]
  }
]

Creating a category (simple items)

As explained previously, the category is a grouper of items. So let's create our first category. For this, we'll use the POST /merchants/{merchantId}/catalogs/{catalogId}/categories API.Request

curl --location --request POST 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/catalogs/10e0fbbe-7279-4ee3-9a2f-caf1f93f7b8e/categories' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
   "name": "Burgers",
   "status": "AVAILABLE",
   "template": "DEFAULT",
   "sequence": 0
}'

Response:

{
  "id": "4e6d3f79-f003-4992-8d4f-4c48d7ac5284",
  "name": "Burgers",
  "sequence": 0,
  "status": "AVAILABLE",
  "template": "DEFAULT"
}

Creating/Editing a complete item

The PUT item endpoint is valid for all types of items, including pizza. The item is created with all the dependencies that compose it: products, option groups and options. If the informed ids already exist in the database, the entities will be updated.Note that, if informed, the values inside contextModifiers will take precedence over the item or option values, for example, if a price is informed in the context modifier, the item price will be overwritten in that context.To create an item with image see the image upload topic.Request:

curl --location --request PUT 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/items' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "item": {
    "id": "cff648d8-fc31-41b0-b80e-81fc3651ca7a",
    "type": "DEFAULT",
    "categoryId": "beab216d-33dc-4ce4-8b35-5372e135093d",
    "status": "AVAILABLE",
    "price": {
      "value": 11.00,
      "originalValue": 12.50
    },
    "externalCode": "public_item",
    "index": 0,
    "productId": "62133b9f-5542-401d-8743-49ec7da8c847",
    "shifts": null,
    "tags": null,
    "contextModifiers": [
      {
        "catalogContext": "WHITELABEL",
        "status": "AVAILABLE",
        "price": {
          "value": 13,
          "originalValue": 16
        },
        "externalCode": "whitelabel_ec2"
      },
      {
        "catalogContext": "INDOOR",
        "status": "AVAILABLE",
        "price": {
          "value": 13,
          "originalValue": 17
        },
        "externalCode": "indoor_ec"
      }
    ]
  },
  "products": [
    {
      "id": "62133b9f-5542-401d-8743-49ec7da8c847",
      "externalCode": "item_product_ec2",
      "name": "X-Burger",
      "description": "Bread, meat, cheese and salad",
      "additionalInformation": "some additional Information",
      "imagePath": "7a27e4ac-c370-4adb-b395-397f503386cc/202311161149_3y9mdsnr8a9.png",
      "ean": "EAN112233414",
      "serving": "SERVES_2",
      "dietaryRestrictions": null,
      "quantity": null,
      "optionGroups": [
        {
            "id":"1e5e5eb5-84c7-4eca-b0c1-921860434f70",
            "min": 0,
            "max": 1
        }
      ]
    },
    {
      "id": "713713e7-641e-44fd-bd92-13ba43daf6a8",
      "externalCode": "option_product_ec2",
      "name": "French Fries",
      "description": "200 g",
      "additionalInformation": "some additional Information",
      "image": null,
      "ean": "EAN112253553344",
      "serving": "SERVES_1",
      "dietaryRestrictions": null,
      "quantity": null,
      "optionGroups": null
    }
  ],
  "optionGroups": [
    {
      "id": "1e5e5eb5-84c7-4eca-b0c1-921860434f70",
      "name": "Sides",
      "externalCode": "option_group_ec2",
      "status": "AVAILABLE",
      "index": 0,
      "optionGroupType": "DEFAULT",
      "optionIds": [
        "d3e31829-a215-47e3-9576-3fddec9417ec"
      ]
    }
  ],
  "options": [
    {
      "id": "d3e31829-a215-47e3-9576-3fddec9417ec",
      "status": "AVAILABLE",
      "index": 0,
      "productId": "713713e7-641e-44fd-bd92-13ba43daf6a8",
      "price": {
        "value": 4,
        "originalValue": 7
      },
      "contextModifiers": [
        {
          "parentOptionId": null,
          "catalogContext": "WHITELABEL",
          "status": "AVAILABLE",
          "price": {
            "value": 5,
            "originalValue": 6
          },
          "externalCode": "op_whitelabel_ec"
        }
      ],
    "fractions": null,
    "externalCode": "option_ec"
    }
  ]
}'

Listing items

Through the GET Items endpoint, informing the id of an existing category, all items, products, option groups and options available in it will be listed. The json format returned is similar to the one used in complete item creation.

curl --location --request GET 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/categories/beab216d-33dc-4ce4-8b35-5372e135093d/items' \
--header 'Authorization: Bearer TOKEN'

Response:

{
   "categoryId": "beab216d-33dc-4ce4-8b35-5372e135093d",
   "items":[
      {
         "id":"cff648d8-fc31-41b0-b80e-81fc3651ca7a",
         "type":"DEFAULT",
         "categoryId":"beab216d-33dc-4ce4-8b35-5372e135093d",
         "status":"AVAILABLE",
         "price":{
            "value":11.00,
            "originalValue":12.50
         },
         "externalCode":"public_item",
         "index":0,
         "productId":"62133b9f-5542-401d-8743-49ec7da8c847",
         "shifts":null,
         "tags":null,
         "contextModifiers":[
            {
              "itemContextId": "600308db-437f-4ec5-84de-aef08d7729d2",
               "catalogContext":"WHITELABEL",
               "status":"AVAILABLE",
               "price":{
                  "value":13,
                  "originalValue":16
               },
               "externalCode":"whitelabel_ec2"
            },
            {
              "itemContextId": "bb4be583-c4d0-4091-bb6b-6e4a552993bf",
               "catalogContext":"INDOOR",
               "status":"AVAILABLE",
               "price":{
                  "value":13,
                  "originalValue":17
               },
               "externalCode":"indoor_ec"
            }
         ]
      }
   ],
   "products":[
      {
         "id":"62133b9f-5542-401d-8743-49ec7da8c847",
         "externalCode":"item_product_ec2",
         "name":"X-Burger",
         "description":"Bread, meat, cheese and salad",
         "additionalInformation":"some additional Information",
         "image":null,
         "ean":"EAN112233414",
         "serving":"SERVES_2",
         "dietaryRestrictions":null,
         "quantity":null,
         "optionGroups":[
           {
             "id":"1e5e5eb5-84c7-4eca-b0c1-921860434f70",
             "min": 0,
             "max": 1
           }
         ]
      },
      {
         "id":"713713e7-641e-44fd-bd92-13ba43daf6a8",
         "externalCode":"option_product_ec2",
         "name":"French Fries",
         "description":"200 g",
         "additionalInformation":"some additional Information",
         "image":null,
         "ean":"EAN112253553344",
         "serving":"SERVES_1",
         "dietaryRestrictions":null,
         "quantity":null,
         "optionGroups":null
      }
   ],
   "optionGroups":[
      {
         "id":"1e5e5eb5-84c7-4eca-b0c1-921860434f70",
         "name":"Sides",
         "externalCode":"option_group_ec2",
         "status":"AVAILABLE",
         "index":0,
         "optionGroupType":"DEFAULT",
         "optionIds":[
            "d3e31829-a215-47e3-9576-3fddec9417ec"
         ]
      }
   ],
   "options":[
      {
         "id":"d3e31829-a215-47e3-9576-3fddec9417ec",
         "status":"AVAILABLE",
         "index":0,
         "productId":"713713e7-641e-44fd-bd92-13ba43daf6a8",
         "price":{
            "value":4,
            "originalValue":7
         },
         "contextModifiers":[
            {
               "parentOptionId":null,
               "catalogContext":"WHITELABEL",
               "status":"AVAILABLE",
               "price":{
                  "value":5,
                  "originalValue":6
               },
               "externalCode":"op_whitelabel_ec"
            }
         ],
         "fractions":null,
         "externalCode":"option_ec"
      }
   ]
}

Listing an item

Similar to the previous endpoint, it's possible to list the resources that compose a single item through its id with GET Item flat. The json format returned is the same used in complete item creation.

curl --location --request GET 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/items/af983271-3981-46fa-94eb-46cb81c439e2/flat' \
--header 'Authorization: Bearer TOKEN'

Response:

{
    "item": {
        "id": "af983271-3981-46fa-94eb-46cb81c439e2",
        "type": "DEFAULT",
        "categoryId": "ea2c31a9-472f-443b-ae8f-72331153915c",
        "status": "AVAILABLE",
        "price": {
            "value": 11,
            "originalValue": 12.5
        },
        "externalCode": "public_item_code",
        "index": 0,
        "productId": "f40ac7e7-da05-4800-90b2-2ee85f486d75",
        "shifts": [
            {
                "startTime": "00:00",
                "endTime": "23:59",
                "monday": true,
                "tuesday": true,
                "wednesday": true,
                "thursday": true,
                "friday": true,
                "saturday": true,
                "sunday": true
            }
        ],
        "contextModifiers": [
            {
                "catalogContext": "WHITELABEL",
                "externalCode": "item_code_for_whitelabel",
                "price": {
                    "value": 13,
                    "originalValue": 16
                },
                "status": "AVAILABLE",
                "itemContextId": "12798f58-ce7b-4195-b719-7ae49d1b2f34"
            },
            {
                "catalogContext": "DEFAULT",
                "status": "AVAILABLE",
                "itemContextId": "78a6faea-1628-4f66-896b-627bc91251bc"
            }
        ]
    },
    "optionGroups": [
        {
            "id": "d65789c8-cc81-47bc-b741-6847d0390fc6",
            "name": "Option Group Name",
            "status": "AVAILABLE",
            "optionGroupType": "DEFAULT",
            "optionIds": [
                "0e1a8e32-0a49-4c15-8b96-d8b7c5c4dc78",
                "b7da158f-4e05-4e2c-9e22-e042baea2a49"
            ]
        },
        {
            "id": "d7955b3a-3cc8-4cd3-983c-31954cee8cff",
            "name": "Option Group Name 3",
            "status": "AVAILABLE",
            "optionGroupType": "DEFAULT",
            "optionIds": [
                "d8957077-36d0-476f-8766-81bac38a69cc"
            ]
        },
        {
            "id": "17532d15-2a2e-4e19-8fc7-3c7cec8bc30c",
            "name": "Option Group Name 2",
            "status": "AVAILABLE",
            "optionGroupType": "DEFAULT",
            "optionIds": [
                "abecc2d8-f91a-4cc7-b66f-59d406748ffb",
                "4034fa88-8804-46c9-8dec-92c8244ec932"
            ]
        }
    ],
    "options": [
        {
            "id": "0e1a8e32-0a49-4c15-8b96-d8b7c5c4dc78",
            "status": "AVAILABLE",
            "index": 0,
            "productId": "220f1d53-3eef-44b1-9f6d-ba2e48d26fd4",
            "price": {
                "value": 4,
                "originalValue": 7
            },
            "externalCode": "option_code",
            "contextModifiers": [
                {
                    "catalogContext": "WHITELABEL",
                    "externalCode": "option_code_for_whitelabel",
                    "price": {
                        "value": 5,
                        "originalValue": 6
                    },
                    "status": "AVAILABLE"
                },
                {
                    "catalogContext": "DEFAULT",
                    "status": "AVAILABLE"
                }
            ]
        },
        {
            "id": "b7da158f-4e05-4e2c-9e22-e042baea2a49",
            "status": "AVAILABLE",
            "index": 0,
            "productId": "abed1844-7220-40b2-abda-fbf86e331209",
            "price": {
                "value": 4,
                "originalValue": 7
            },
            "externalCode": "option_code2",
            "contextModifiers": [
                {
                    "catalogContext": "WHITELABEL",
                    "externalCode": "option_code_for_whitelabel2",
                    "price": {
                        "value": 5,
                        "originalValue": 6
                    },
                    "status": "AVAILABLE"
                },
                {
                    "catalogContext": "DEFAULT",
                    "status": "AVAILABLE"
                }
            ]
        },
        {
            "id": "d8957077-36d0-476f-8766-81bac38a69cc",
            "status": "AVAILABLE",
            "index": 0,
            "productId": "eec65205-110d-43aa-9729-e4ebcf9f8106",
            "price": {
                "value": 4,
                "originalValue": 7
            },
            "externalCode": "option_code5",
            "contextModifiers": [
                {
                    "catalogContext": "WHITELABEL",
                    "externalCode": "option_code_for_whitelabel5",
                    "price": {
                        "value": 5,
                        "originalValue": 6
                    },
                    "status": "AVAILABLE"
                },
                {
                    "catalogContext": "DEFAULT",
                    "status": "AVAILABLE"
                }
            ]
        },
        {
            "id": "abecc2d8-f91a-4cc7-b66f-59d406748ffb",
            "status": "AVAILABLE",
            "index": 0,
            "productId": "2b9da9a4-e4f4-46cb-8d29-687fbd3a7f6f",
            "price": {
                "value": 4,
                "originalValue": 7
            },
            "externalCode": "option_code3",
            "contextModifiers": [
                {
                    "catalogContext": "WHITELABEL",
                    "externalCode": "option_code_for_whitelabel3",
                    "price": {
                        "value": 5,
                        "originalValue": 6
                    },
                    "status": "AVAILABLE"
                },
                {
                    "catalogContext": "DEFAULT",
                    "status": "AVAILABLE"
                }
            ]
        },
        {
            "id": "4034fa88-8804-46c9-8dec-92c8244ec932",
            "status": "AVAILABLE",
            "index": 0,
            "productId": "7c878419-e240-417d-a322-5c32f06f47c6",
            "price": {
                "value": 4,
                "originalValue": 7
            },
            "externalCode": "option_code4",
            "contextModifiers": [
                {
                    "catalogContext": "WHITELABEL",
                    "externalCode": "option_code_for_whitelabel4",
                    "price": {
                        "value": 5,
                        "originalValue": 6
                    },
                    "status": "AVAILABLE"
                },
                {
                    "catalogContext": "DEFAULT",
                    "status": "AVAILABLE"
                }
            ]
        }
    ],
    "products": [
        {
            "id": "f40ac7e7-da05-4800-90b2-2ee85f486d75",
            "name": "Default name",
            "description": "Default description",
            "ean": "EAN112233414",
            "serving": "SERVES_2",
            "dietaryRestrictions": [],
            "optionGroups": [
                {
                    "id":"d65789c8-cc81-47bc-b741-6847d0390fc6",
                    "min": 0,
                    "max": 1
                },
                {
                    "id":"d7955b3a-3cc8-4cd3-983c-31954cee8cff",
                    "min": 1,
                    "max": 1
                },
                {
                    "id":"17532d15-2a2e-4e19-8fc7-3c7cec8bc30c",
                    "min": 0,
                    "max": 1
                }
            ]
        },
        {
            "id": "220f1d53-3eef-44b1-9f6d-ba2e48d26fd4",
            "name": "Option name",
            "externalCode": "option_product_code",
            "description": "Default description",
            "ean": "EAN112253553344",
            "serving": "SERVES_1",
            "dietaryRestrictions": [],
            "optionGroups": []
        },
        {
            "id": "abed1844-7220-40b2-abda-fbf86e331209",
            "name": "Option name 2",
            "externalCode": "option_product_code2",
            "description": "Default description",
            "ean": "EAN112253553344",
            "serving": "SERVES_1",
            "dietaryRestrictions": [],
            "optionGroups": []
        },
        {
            "id": "eec65205-110d-43aa-9729-e4ebcf9f8106",
            "name": "Option name 5",
            "externalCode": "option_product_code5",
            "description": "Default description",
            "ean": "EAN112253553344",
            "serving": "SERVES_1",
            "dietaryRestrictions": [],
            "optionGroups": []
        },
        {
            "id": "2b9da9a4-e4f4-46cb-8d29-687fbd3a7f6f",
            "name": "Option name 3",
            "externalCode": "option_product_code3",
            "description": "Default description",
            "ean": "EAN112253553344",
            "serving": "SERVES_1",
            "dietaryRestrictions": [],
            "optionGroups": []
        },
        {
            "id": "7c878419-e240-417d-a322-5c32f06f47c6",
            "name": "Option name 4",
            "externalCode": "option_product_code4",
            "description": "Default description",
            "ean": "EAN112253553344",
            "serving": "SERVES_1",
            "dietaryRestrictions": [],
            "optionGroups": []
        }
    ]
}

Discovering items that are for sale in the catalog

This endpoint returns all items that are for sale in the menu : GET /merchants/{merchantId}/catalogs/{groupId}/sellableItems The groupId is the information returned as a parameter in the response from the GET /merchants/{merchantId}/catalogs endpoint

curl --location --request https://merchant-api.ifood.com.br/catalog/v2.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/catalogs/ffca0022-eb43-4205-9a1b-73a72f8e3f95/sellableItems --header 'Authorization: Bearer TOKEN

Response:

[
  {
    "itemId": "ec16fb62-7bdd-43e4-940c-10b5a2845f13",
    "categoryId": "4e6d3f79-f003-4992-8d4f-4c48d7ac5284",
    "itemEan": "",
    "itemExternalCode": "BG-1",
    "categoryName": "Burgers",
    "categoryIndex": 0,
    "itemName": "X-burger",
    "itemDescription": "Bread, meat and cheese",
    "itemAdditionalInformation": "",
    "logosUrls": [],
    "itemIndex": 0,
    "itemPrice": {
      "value": 20,
      "originalValue": 30
    },
    "itemMinSalePrice": 20,
    "itemSchedules": [],
    "itemPackaging": "string",
    "itemQuantity": 0,
    "itemUnit": "string",
    "itemOptionGroups": [],
    "itemSellingOption": {
      "minimum": 0,
      "incremental": 0,
      "availableUnits": [
        "g"
      ]
    },
    "itemGeneralTags": [],
    "itemProductTags": [
      {
        "group": "PORTION_SIZE",
        "tags": [
          "SERVES_2"
        ]
      }
    ]
  }
]

Discovering items that are not for sale in the catalog and understanding the reason

This endpoint returns all items that are not for sale in the menu with the reason for the restriction: GET /merchants/{merchantId}/catalogs/{catalogId}/unsellableItems

curl --location --request https://merchant-api.ifood.com.br/catalog/v2.0/merchants/1cdfa2d0-6c89-4ca8-a544-3b39009fe03c/catalogs/1cdfa2d0-6c89-4ca8-a544-3b39009fe03c/unsellableItems --header 'Authorization: Bearer TOKEN

Response:

{
  "categories": [
    {
      "id": "ccf719e9-8fc3-4264-8dff-832ae9e901a8",
      "status": "AVAILABLE",
      "template": "DEFAULT",
      "restrictions": [],
      "unsellableItems": [
        {
          "id": "32545e4b-6664-411f-83c3-524771750fbd",
          "productId": "400c9fc5-f1bb-4538-a2b5-a6d4a98d1a01",
          "restrictions": [
            "ITEM_PAUSED"
          ]
        },
        {
          "id": "fb3cc740-d1ff-43cf-87ef-22491fe2381b",
          "productId": "a22f334e-90c8-4474-8dfe-48ff3a4affe3",
          "restrictions": [
            "ITEM_PAUSED"
          ]
        },
        {
          "id": "7cb6cc89-bebe-489d-9866-7ff4689b2771",
          "productId": "16744979-0280-473b-ae2b-b671de7ffe9c",
          "restrictions": [
            "ITEM_PAUSED"
          ]
        }
      ]
    },
    {
      "id": "86cbba43-51f7-439c-a3c6-ecd0a7c9f402",
      "status": "UNAVAILABLE",
      "template": "DEFAULT",
      "restrictions": [
        "CATEGORY_PAUSED"
      ],
      "unsellableItems": [
        {
          "id": "a6a608e4-6548-442c-8b9f-9fcb6bcb9ef3",
          "productId": "3a9d9df9-18c7-48d0-b0c6-92fc4b5b2a19",
          "restrictions": [
            "CATEGORY_PAUSED",
            "ITEM_PAUSED"
          ]
        },
        {
          "id": "044abde5-dba4-44f0-b039-0da51ddde2a1",
          "productId": "4b31bae7-e415-42f1-b023-dad5083c1cb2",
          "restrictions": [
            "CATEGORY_PAUSED",
            "ITEM_PAUSED"
          ]
        }
      ]
    }
  ]
}

Possible restrictions are:

Restriction	Reason
CATEGORY_HAS_VIOLATION	Some type of iFood rule violation was detected in the category
CATEGORY_PAUSED	Category paused
ITEM_PAUSED	Item paused
ITEM_HAS_VIOLATION	Some type of iFood rule violation was detected in the item
ITEM_PRICE_MISSING	Item without price
ITEM_AND_OPTIONS_PRICES_MISSING	The item value with its mandatory options can be zero
ITEM_OUT_OF_STOCK	Item out of stock
INVALID_OPTION_GROUP_MAX_QUANTITY	Maximum value of group options is less than or equal to zero
OPTION_GROUP_WITHOUT_AVAILABLE_OPTIONS	Option group without sellable options
OPTION_GROUP_MAX_SMALLER_THAN_MIN	Maximum value of group options is less than minimum
OPTION_GROUP_PAUSED	Option group paused
OPTION_PAUSED	Option paused
OPTION_OUT_OF_STOCK	Option out of stock

Creating inventory for a product

curl -X POST "https://merchant-api.ifood.com.br/catalog/v2.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/inventory"
-H "accept: application/json" -H "Content-Type: application/json"
-d "{\"productId\":\"ec16fb62-7bdd-43e4-940c-10b5a2845f13\",\"amount\":10}"

Listing product inventory

curl -X GET "https://merchant-api.ifood.com.br/catalog/v2.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/inventory/ec16fb62-7bdd-43e4-940c-10b5a2845f13"
-H "accept: application/json""

Deleting product inventory

curl -X POST "https://merchant-api.ifood.com.br/catalog/v2.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/inventory/batchDelete"
-H "accept: */*" -H "Content-Type: application/json"
-d "{\"productIds\":[\"ec16fb62-7bdd-43e4-940c-10b5a2845f13\"]}"

Validating the catalog

With everything registered, let's see how the listing of categories in your catalog turned out? As mentioned earlier, the GET /merchants/{merchantId}/catalogs/{catalogId}/categories API will be used

curl --location --request GET 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/catalogs/10e0fbbe-7279-4ee3-9a2f-caf1f93f7b8e/categories?includeItems=true \
--header 'Authorization: Bearer TOKEN

Result:

[
  {
    "id": "4e6d3f79-f003-4992-8d4f-4c48d7ac5284",
    "name": "Burgers",
    "status": "AVAILABLE",
    "sequence": 0,
    "template": "DEFAULT",
    "items": [
      {
        "id": "a51939d2-e2d6-4bf5-8161-f957bc4ee895",
        "name": "X-burger",
        "description": "Bread, meat and cheese",
        "externalCode": "BG-1",
        "status": "AVAILABLE",
        "sequence": 0,
        "productId": "ec16fb62-7bdd-43e4-940c-10b5a2845f13",
        "imagePath": "",
        "price": {
          "value": 20,
          "originalValue": 30
        },
        "shifts": [
          {
            "startTime": "00:00",
            "endTime": "23:59",
            "monday": true,
            "tuesday": true,
            "wednesday": true,
            "thursday": true,
            "friday": true,
            "saturday": true,
            "sunday": true
          }
        ],
        "serving": "SERVES_1",
        "dietaryRestrictions": ["ORGANIC"],
        "optionGroups": [
          {
            "id": "daf9ba2c-dca9-43b1-b02a-0fc2c4b01967",
            "name": "Choose your drink",
            "min": 0,
            "max": 1,
            "sequence": 0,
            "status": "AVAILABLE",
            "options": [
              {
                "id": "02740dbe-bfc0-4609-aabd-55316590638e",
                "name": "Coca-Cola can",
                "description": "300 ml",
                "externalCode": "LT-1",
                "status": "AVAILABLE",
                "sequence": 0,
                "imagePath": "",
                "price": {
                  "value": 5
                }
              }
            ]
          }
        ]
      }
    ]
  }
]

Changing price of items and options in batch - Async

It's possible to edit the price in batch by productId or by externalCode. The example below uses externalCode, but if you want to use productId just replace the field "externalCode":"burguerX43" with "productId":"058dd32f-3b26-41e9-aa39-30a64d3f2b81". If both externalCode and productId are informed, the change will be made only considering the externalCode. There's an optional parameter catalogContext to inform in which context the change will be made. If the parameter is not informed, the change will be effective in all contexts that match the informed productId or externalCode.Request

    curl --location --request PATCH 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/411347fb-adc5-456f-95be-03cf10a5b8b5/products/price' \
    --header 'accept: application/json' \
    --header 'Content-Type: application/json' \
    --data-raw '[{
      "externalCode":"burguerX43",
      "price": {
        "value":25,
        "originalValue":30
      },
      "resources":["ITEM", "OPTION"]
    }]'

To update only ITEM, the resources field should be equal to "resources":["ITEM"]. The same applies to OPTIONS.

Response

{
  "batchId": "311afcf1-541a-41af-a9a5-4651d676731e",
  "url": "/v2.0/merchants/411347fb-adc5-456f-95be-03cf10a5b8b5/batch/311afcf1-541a-41af-a9a54651d676731e"
}

Changing status of items and options in batch - Async

It's possible to edit the status in batch by productId or by externalCode. The example below uses externalCode, but if you want to use productId just replace the field "externalCode":"burguerX43" with "productId":"058dd32f-3b26-41e9-aa39-30a64d3f2b81". If both externalCode and productId are informed, the change will be made only considering the externalCode. There's an optional parameter catalogContext to inform in which context the change will be made. If the parameter is not informed, the change will be effective in all contexts that match the informed productId or externalCode.Request

    curl --location --request PATCH 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/411347fb-adc5-456f-95be-03cf10a5b8b5/products/status' \
    --header 'accept: application/json' \
    --header 'Content-Type: application/json' \
    --data-raw '[{
      "externalCode":"burguerX43",
      "status": "UNAVAILABLE",
      "resources":["ITEM", "OPTION"]
    }]'

To update only ITEM, the resources field should be equal to "resources":["ITEM"]. The same applies to OPTIONS.

Response

{
  "batchId": "6762714f-6d58-4eac-8f0f-9b878c8b6c30",
  "url": "/v2.0/merchants/411347fb-adc5-456f-95be-03cf10a5b8b5/batch/6762714f-6d58-4eac-8f0f-9b878c8b6c30"
}

Following batch operations

Batch operations can be performed in situations such as updating many products. To check which operations were successful or not, and if the entire batch has been processed, we use the batch operations result listing API GET /merchants/{merchantId}/batch/{batchId}

curl --location --request GET 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/6b487a27-c4fc-4f26-b05e-3967c2331882/batch/bca9a293-b121-4027-b3e3-bce675581fbd' \
--header 'Authorization: Bearer TOKEN'

Result:

{
  "batchStatus": "COMPLETED",
  "results": [
    {
      "resourceId": "fd1c993b-4882-44e7-8c21-aa7d637ccdf8",
      "result": "SUCCESS"
    },
    {
      "resourceId": "ec16fb62-7bdd-43e4-940c-10b5a2845f13",
      "result": "SUCCESS"
    }
  ]
}

Changing option price

With the PATCH Option Price endpoint it's possible to globally edit the price of an option by passing the price field with the desired value, as well as to change it in a specific menu, the priceByCatalog field should be filled respectively with its values and the context of the changed menu.

curl --location --request PATCH 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/options/price' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "optionId": "d3e31829-a215-47e3-9576-3fddec9417ec",
  "price": {
    "value": 5,
    "originalValue": 7
  },
  "parentCustomizationOptionId": null,
  "priceByCatalog": [
    {
      "value": 5,
      "originalValue": 7,
      "catalogContext": "WHITELABEL"
    }
  ]
}'

Changing option status

With behavior similar to price change, it's possible to globally edit the status of an option with PATCH Option Status by passing the status field with the desired condition, as well as to change it in a specific menu, the statusByCatalog field should be filled respectively with the status and the context of the changed menu.

curl --location --request PATCH 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/options/status' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "optionId": "d3e31829-a215-47e3-9576-3fddec9417ec",
  "status": "AVAILABLE",
  "parentCustomizationOptionId": null,
  "statusByCatalog": [
    {
      "status": "UNAVAILABLE",
      "catalogContext": "WHITELABEL"
    }
  ]
}'

Changing option external code

Through PATCH Option External Code it's possible to globally edit the external code of an option by passing the externalCode field with the desired code, as well as to change it in a specific menu, the externalCodeByCatalog field should be filled respectively with the code and the context of the changed menu.

curl --location --request PATCH 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/options/externalCode' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "optionId": "d3e31829-a215-47e3-9576-3fddec9417ec",
  "externalCode": "tst-external-code",
  "parentCustomizationOptionId": null,
  "externalCodeByCatalog": [
    {
      "externalCode": "tst-external-code2",
      "catalogContext": "WHITELABEL"
    }
  ]
}'

Changing item price

Similar to the options endpoint, it's possible to globally edit the price of an item with PATCH Item Price by passing the price field with the desired value, as well as to change it in a specific menu, the priceByCatalog field should be filled respectively with its values and the context of the changed menu.

curl --location --request PATCH 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/items/price' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "itemId": "1621d43c-1ac0-4407-9d79-50e974bbcc90",
  "price": {
    "value": 25,
    "originalValue": 30
  },
  "priceByCatalog": [
    {
      "value": 23,
      "originalValue": 27,
      "catalogContext": "WHITELABEL"
    }
  ]
}'

Changing item status

With behavior similar to price change, it's possible to globally edit the status of an item through PATCH Item Status by passing the status field with the desired condition, as well as to change it in a specific menu, the statusByCatalog field should be filled respectively with the status and the context of the changed menu.

curl --location --request PATCH 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/items/status' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "itemId": "1621d43c-1ac0-4407-9d79-50e974bbcc90",
  "status": "AVAILABLE",
  "statusByCatalog": [
    {
      "status": "UNAVAILABLE",
      "catalogContext": "WHITELABEL"
    }
  ]
}'

Changing item external code

With the PATCH Item External Code endpoint it's possible to globally edit the external code of an item by passing the externalCode field with the desired code, as well as to change it in a specific menu, the externalCodeByCatalog field should be filled respectively with the code and the context of the changed menu.

curl --location --request PATCH 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/items/externalCode' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "itemId": "d3e31829-a215-47e3-9576-3fddec9417ec",
  "externalCode": "tst-external-code",
  "externalCodeByCatalog": [
    {
      "externalCode": "tst-external-code2",
      "catalogContext": "WHITELABEL"
    }
  ]
}'

Image upload

To add images to your product in the POST or PUT product endpoints and in the PUT item endpoint you need to send the product imagePath field filled with the return from the endpoint below: Upload Image:

curl --location --request POST 'https://merchant-api.ifood.com.br/catalog/v2.0/merchants/21131c93-0398-4818-aad3-762cab309a26/image/upload/' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "image": "data:image/png;base64,imageBase64"
}'

By uploading your image through this endpoint you can reuse the same image in multiple products.
Image upload from the image field with a base64 also continues to work for the POST and PUT product endpoints.Supported image formats are: 'jpg', 'jpeg' and 'png'.

Image size

The size limit for image files (regardless of format) is 5MB. Requests (both in the Image Upload endpoint and other endpoints) with a request body larger than 5MB will return with status 413 (Entity Too Large).

Was this page helpful?

Rate your experience in the new Developer portal: