Products

Create or Update Product

Changed on

This API allows to create or update a product (if the product already exists, its data is updated, otherwise it is created), or to analyze a test product (in which case no product is created or updated). To analyze a product, the "code" path component needs to contain the value "test" instead of a barcode.

New API to send structured product data in a JSON format instead of in a flattened list of key / value pairs field as-in the current product add / edit API that relies on a multipart/form-data format.

Important: this new Product WRITE API has been deployed in production, but it is still under development, and it may change.

This new API is used in particular to send structured packaging data: https://openfoodfacts.github.io/openfoodfacts-server/dev/explain-packaging-data/

The new API is gradually being extended to support other product fields.

Currently supported fields are:

  • language specific fields (e.g. product name, ingredients text)
  • tags fields (e.g. categories, labels)
  • packaging fields (e.g. packagings, packagings_add, packagings_complete)
  • image selection of uploaded images (e.g. front, ingredients, nutrition, packaging) for specific languages
patch/api/v3/product/{code}

Request

  • Base URL
    https://world.openfoodfacts.org
  • Auth
    API key in cookie session and API key in header User-Agent

Path parameters

codestring required
Example:3017620422003

The barcode of the product to create or update, or "test" to analyze the product data sent without creating or updating a product.

Request body

lcstring

2 letter code of the language of the interface. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the language may be inferred by the country of the user (passed through the cc field or inferred by the IP address). Full list at https://static.openfoodfacts.org/data/taxonomies/languages.json

ccstring

2 letter code of the country of the user. Used for localizing some fields in returned values (e.g. knowledge panels). If not passed, the country may be inferred by the IP address of the request. Full list at https://static.openfoodfacts.org/data/taxonomies/countries.json

fieldsstring

Comma separated list of fields requested in the response. Special values: "updated": returns field that were updated by the query (e.g. sending "packagings" or "packagings_add" would return "packagings"), "none": returns no fields, "all": returns all fields except generated fields that need to be explicitly requested such as "knowledge_panels". Defaults to "updated" for WRITE requests, and "all" for READ requests.

tags_lcstring

2 letter language code to request names of tags in a specific language.

For READ requets: if passed, all taxonomized tags of the response will include a lc_name property with the translation in the requested language, if available. Otherwise, the property value will contain the name in the original language, prefixed by the 2 language code and a colon.

For WRITE requests: if passed, taxonomized tags fields with a lc_name property will be considered to be in this language.

user_idstring
passwordstring password

Password for login

Example request

{
  "fields": "product_name,packagings",
  "tags_lc": "fr"
}

Response

The response will include a "product" structure. The fields returned in this structure will depend on the value of the "fields" input field:

  • "updated" (default): all fields updated by the query will be returned, including fields that are directly generated from the updated fields. For instance, sending "packagings" or "packagings_add" will return the "packagings" field.

  • "none": no fields are returned.

  • "all": returns all fields except generated fields that need to be explicitly requested such as "knowledge_panels".

The "fields" values can also be concatenated: "all,knowledge_panels"

status'success' | 'success_with_warnings' | 'success_with_errors' | 'failure'

Overall status of the request: whether it failed or succeeded, with or without warnings or errors.

Example response

{
  "status": "success_with_errors",
  "result": {
    "id": "product_updated",
    "name": "Product updated",
    "lc_name": "Produit mis à jour"
  },
  "errors": [
    {
      "message": {
        "id": "sugars_higher_than_carbohydrates",
        "name": "Sugars higher than carbohydrates",
        "lc_name": "Sucres plus élevés que les glucides",
        "description": "Sugars (40g) are higher than carbohydrates (35g).",
        "lc_description": "Les sucres (40g) sont plus élévés que les glucdes."
      },
      "field": {
        "id": "nutriment.sugars",
        "value": "40"
      },
      "impact": {
        "id": "nutrients_not_updated",
        "name": "Nutrients not updated",
        "lc_name": "Nutriments non mis à jour",
        "description": "The nutrients were not updated.",
        "lc_description": "Les nutriments n'ont pas été mis à jour."
      }
    }
  ]
}

Changes

    • breaking

      added to the request body allOf list

    • breaking

      added subschema #3 to the allOf[subschema #3]/product request property allOf list

    • breaking

      the allOf[subschema #3]/product request property type changed from no type to object

    5 more changes in this revision