e-label information

Introduction

Electronic labeling, or e-labels, for wine and spirits is governed by EU Regulation 2019/787, which is also known as the "Wine Act". This regulation sets the rules for the production, presentation, and labeling of wine, including the use of e-labels. In addition, the EU Regulation 1169/2011 (Food Information to Consumers Regulation or FIC Regulation) also sets the requirements for labeling.

e-labels appear on product packaging or on digital marketing materials and must contain all of the legally required information about a product, including, the product name or brand, volume, alcohol content, ingredients, and allergen information. The e-label format must comply with the EU regulations for food and beverage labeling, including the requirements for font size, language, and legibility.

There are 3 ways e-labels can be managed in Scantrust

Edit e-label data in the scantrust portal under the products > e-label page
Using the Scantrust excel file bulk upload feature available in our enterprise plans
Upload the e-label data for each product with the Scantrust e-label JSON API

e-label-1 e-label-2

The below process describes how to upload and download e-label data using the Scantrust REST Api. Because e-label data is set on the product, you will need a UAT token with the same minimum permissions as for managing products:

product_create
product_delete
product_edit
product_view

The UAT token must be set in the header fields of all requests as described in Authentication & Tokens.

API Design

POST: /api/v2/products/{product_id}/elabel/

Sets all e-label JSON data for a product

Response (201): Status CREATED

{
  "name": "demoproduct", // product sku
  "is_published": false,
  "data": {
    "editor": { ... },
    "published": { ... }
  }
}

Note that a complete JSON object needs to be posted each time an e-label is updated. This endpoint does not support partial updates of the JSON.

For an example of a full set of data to POST for the editor section, see JSON example here

Once the data object is ready to be published, you will need to do another POST request to set the is_published flag to true.

GET: /api/v2/products/{product_id}/elabel/

Returns all e-label JSON data for a product

Response (200): Status OK

Example JSON:

{
  "id": 1272,
  "company": 7583,
  "name": "black-deer-cb-2018",
  "data": {
    "editor": {
      "type": "wine",
      "theme": { "primary": "#F01515", "background": "#D8D790", "alcoholColor": "#890022" },
      "footer": { "first_line": "", "second_line": "" },
      "header": { "logo": "", "title": "E-Label" },
      "default_country": "",
      "default_language": "en",
      "reviewed_languages": ["en"],
      "available_languages": ["en"],
      "enforce_language_per_country": false,
      "sections": [
        { "key": "product-infos" },
        { "key": "geographical-indications" },
        { "key": "serving-infos" },
        { "key": "ingredients" },
        { "key": "allergens" },
        { "key": "nutrition" },
        { "key": "responsible-consumption" },
        { "key": "sustainability" },
        { "key": "business-operator" },
        { "key": "brand-infos" }
      ],
      ... (JSON objects for each of the above sections)
    "published": {
      ...
    }

An e-label JSON contains 2 set of the e-label data at all time.

editor : draft version of the data, the data that you see in when using the e-label management tool.
published : Live data. What consumer see when they open an e-label landing page.

The elabel JSON consists of a set of generic fields and 10 sections each with its own JSON object:

Generic Fields

type : wine, spirit or aromatised_wine
theme : sets the primary, background and alcoholColor of the landing page
footer : sets the text for the first_line and second_line of the e-label footer
header : sets the logo and title (default: "E-Label")
default_country : sets the data for the country to be shown when an e-label is scanned in a non-EU country. This is a 2 letter uppercase country code, eg: 'FR' for France
default_language : sets the default language (default: English), this is a 2 letter lowercase language code, eg: 'en' for English
reviewed_languages : array of reviewed languages available to users on the landing page.
available_languages : array of available languages that may not have been reviewed yet. The review process happens in the translation section of the e-label editor. Once a language gets 'approved' it will be added to the reviewed_languages array.
enforce_language_per_country : forces a fixed language for each country (default: false)

Section Objects

Product Information product-infos
Ingredients ingredients
Serving Information serving-infos
Nutrition Table nutrition
Responsible Consumption Message responsible-consumption
Sustainability Certifications sustainability
Geographic Indications geographical-indications
Business Operators business-operator
Branding Info brand-info
Impressum impressum

Each section contains variable information inluding country specific data and translations fields as well as pre-translated system keys

These fields will be formatted as follow:

  /* country specific field */
  "serving": {
    "default": 100, // default value
    "FR": 76 // country specific value
    ...
  }

  /* translations field */
  "product_name": {
    "en": "Demo Product Name",
    "de": "Name des Demoprodukts",
    "fr": "Nom du produit de démonstration"
    ...
  }

  /* system key field */
  "type": "wine_type_wine"

  /* non-translated field */
  "vine_variety": "Merlot"

Fallback behaviour:

for country specific fields, if a the country does not have a specific value, it will fallback to the default value.
for translations fields, if there is no entry for the selected language on the landing page, it will fallback to the default_language value

System keys

System keys are a set of pre-translated value used throughout the e-label. All the values that you can usually see from our various dropdown in the editor are based on system keys. When possible, you should use these keys since it would greatly reduce the workload required to create an e-label JSON since all the translations would automatically work for these terms.

For a full list of system keys please refer to this page

In most cases, a system key field can also be used like a translations field by simply replacing the content from a key to an object containing the translations.

product-infos

System key fields:

type
wine_sweetness
wine_colour
production_method
bottled_in_protected_atmosphere: Only needed if product uses packaging gases

Translation fields:

product_name
sales_description
traditional_terms
production_method: use system key if possible
type: use system key if possible

Non-translated fields:

vine_variety

Other fields

origin: 2 letter uppercase country code array
volumes: bottle volumes in ML string array
alcohol_volume: alcohol volume as a string

  "product-infos": {
    "type": "wine_type_wine",
    "origin": [
      "FR"
    ],
    "volumes": [
      "750"
    ],
    "product_name": {
      "en": "Demo Product Name",
      "de": "Name des Demoprodukts",
      "nl": "",
      "fr": "Nom du produit de démonstration"
    },
    "alcohol_volume": "13",
    "sales_description": {
      "en": "A product description",
      "de": "Eine Produktbeschreibung",
      "fr": "Une description du produit"
    },
    "traditional_terms": {},
    "bottled_in_protected_atmosphere": "bottled_in_protected_atmosphere_1",
    "vintage_year": "2018",
    "wine_sweetness": "wine_sweetness_extra_dry",
    "vine_variety": "Merlot",
    "wine_colour": "wine_colour_red",
    "production_method": "production_methods_barrel_aged"
  }

ingredients

There are 2 ways of declaring your ingredient list:

Using the scantrust system keys: set use_free_form to false. This is the recommended approach
Free text field: set use_free_form to true

If you chose to use the free text field option, you will need to fully format and translate your ingredient list according to the regulations. If you use the system keys, all the formatting and translations will be handled automatically by the e-label landing page.

Declare using system keys

Each ingredient is an individual object in the list array and uses the following attributes:

category: system-key field
description: system-key field, can also contain translations
is_organic: boolean, defines if an ingredient should appear as organic
is_allergen: boolean, defines if an ingredient should appear as allergen
is_contained_display: boolean, this defines how a category should be formatted. This will only affect a few specific categories, if you aren't sure how a category should be displayed, set this to false

"ingredients": {
  "list": [
    {
      "category": "ingredient_category_main_ingredients",
      "description": "ingredient_grapes",
      "is_contained_display": false,
      "is_organic": true
    },
    {
      "description": "ingredient_calcium_sulfate",
      "category": "ingredient_category_acidity_regulators",
      "is_contained_display": false
    },
    {
      "description": "ingredient_tartaric_acid",
      "category": "ingredient_category_acidity_regulators",
      "is_contained_display": false
    },
    {
      "description": {
        "en": "Special ingredient",
        "fr": "Ingrédient spécial"
        ...
      },
      "category": "ingredient_category_antioxidant",
      "is_allergen": true
    }
  ],
  "free_text": {
    "en": "Alcohol of vine origin*, Acidity regulators contains Calcium sulphate and/or Tartaric acid (L(+)-), Colours",
    "fr": "Alcool d'origine viticole*, Régulateurs d'acidité contient Sulfate de calcium et/ou Acide tartrique [L(+)-], colorants"
    ...
  },
  "use_free_form": false
},

serving-infos

Country specific fields:

unit: Unit to show for the serving size & volume for a specific country. Only CL and ML are currently supported
serving: Serving size per country in ML

System key fields:

glass_icon: Glass icon displayed on the landing page page
bottle_icon: Bottle icon displayed on the page

"serving-infos": {
  "unit": {
    "FR": "CL",
    "default": "ML"
  },
  "serving": {
    "default": 100,
    "FR": 75
  },
  "glass_icon": "default_wine",
  "bottle_icon": "default_wine"
},

nutrition

The nutrition table is an array containing each nutritional information line as well as some nested information under specific items.

Fields: key: System key, do not change unit: Unit displayed for that line, do not change per_100ml: Number less_operator: Set to true if you want the entry to show as < 0g instead of 0g

The structure and order of this table has to be identical to the example below in order to respect the regulation.

 "nutrition": {
    "table": [
      {
        "key": "energy",
        "unit": "kJ",
        "children": [
          {
            "key": null,
            "unit": "kcal",
            "per_100ml": 75,
            "less_operator": false
          }
        ],
        "per_100ml": 312,
        "less_operator": false
      },
      {
        "key": "fat",
        "unit": "g",
        "children": [
          {
            "key": "saturated_fat",
            "unit": "g",
            "per_100ml": 0.5,
            "less_operator": false
          }
        ],
        "per_100ml": 0.5,
        "less_operator": false
      },
      {
        "key": "carbohydrate",
        "unit": "g",
        "children": [
          {
            "key": "sugar",
            "unit": "g",
            "per_100ml": 0,
            "less_operator": false
          }
        ],
        "per_100ml": 0.4,
        "less_operator": false
      },
      {
        "key": "protein",
        "unit": "g",
        "per_100ml": 0,
        "less_operator": false
      },
      {
        "key": "salt",
        "unit": "g",
        "per_100ml": 0.5,
        "less_operator": false
      }
    ]
  },

responsible-consumption

Translations fields

description: Custom responsible consumption message

System keys fields

icons: Array of system keys icons.

Other fields

show_responsible_message: Show default responsible message: "Alcohol abuse is dangerous to your health."
responsible_drinking_logo: Show the "Wine in moderation" or "Drink responsibly" official images depending on your product type.
custom_icons: Array of custom icons.
- name: file name, internal
- url: file url
- wide: boolean, defines if the image should take the full width of the screen when displayed
- countries: Array of countries where the icon should be visible. Use all to show everywhere, use 2 letter uppercase country code otherwise

"responsible-consumption": {
  "icons": [
    "0",
    "1",
    "2"
  ],
  "description": {
    "en": "Don't drink and drive",
    "fr": "Boire ou conduire, il faut choisir"
  },
  "custom_icons": [
    {
      "name": "custom image",
      "url": "https://cc.staging.scantrust.io/c/6644/stcfile/blob-ngneoq",
      "wide": false,
      "countries": [
        "all"
      ]
    }
  ],
  "show_responsible_message": true,
  "responsible_drinking_logo": true
},

sustainability

Translation fields

organic_description: A sustainability message related to organic
recyclability_description: A sustainability message related to recyclability
certifications_description: A sustainability message related to certifications

System keys fields

organic_icons: Array of system keys icons.
recyclability_icons: Array of system keys icons.
certifications_icons: Array of system keys icons.

Other fields

italian_recyclability: Italian recycling law module, no documentation available yet, keep the structure identical to the example json below.
custom_icons: Array of custom icons.
- name: file name, internal
- url: file url
- wide: boolean, defines if the image should take the full width of the screen when displayed
- countries: Array of countries where the icon should be visible. Use all to show everywhere, use 2 letter uppercase country code otherwise

"sustainability": {
  "custom_icons": [
    {
      "name": "custom image",
      "url": "https://cc.staging.scantrust.io/c/6644/stcfile/blob-ngneoq",
      "wide": false,
      "countries": [
        "all"
      ]
    }
  ],
  "organic_icons": [
    "1",
    "2"
  ],
  "organic_description": {
    "en": "An organic message",
    "de": "Eine organische Botschaft",
    "fr": "Un message organique"
    ...
  },
  "recyclability_icons": [
    "6"
  ],
  "certifications_icons": [
    "1"
  ],
  "italian_recyclability": {
    "list": [],
    "is_enabled": false
  },
  "recyclability_description": {
    "en": "A sustainability message",
    "de": "Eine Botschaft zur Nachhaltigkeit",
    "fr": "Un message de durabilité"
    ...
  },
  "certifications_description": {
    "en": "A certification message",
    "de": "Eine Zertifizierungsnachricht",
    "fr": "Un message de certification"
    ...
  }
},

geographical-indications

System keys fields:

icon: PDO / PGI system key icon

Non-translated fields:

description

"geographical-indications": {
  "list": [
    {
      "description": "AOC Pinot noir",
      "icon": "0"
    }
  ]
},

business-operator

Country specific fields:

bottled_by: Bottler address per country
imported_by: Importer address per country
producted_by: Producer address per country

"business-operator": {
  "bottled_by": {
    "default": "Chateau Demo, 333 avenue de Bordeaux",
    "FR": "Custom bottler address for France"
  },
  "imported_by": {
    "default": "Importer Name, 333 avenue de Bordeaux",
    "FR": "Custom importer address for France"
  },
  "produced_by": {
    "default": "Chateau Demo, 333 avenue de Bordeaux",
    "FR": "Custom producer address for France"
  }
},

brand-info

Translation fields

description

Other fields

image: Image url
text_color: Text color as an hex string
link: URL to the brand website. Only available for spirit template type

"brand-infos": {
  "link": "",
  "image": "https://cc.staging.scantrust.io/c/6644/stcfile/blob-joobpu",
  "text_color": "#FFFFFF",
  "description": {
    "en": "Brand message",
    "fr": "Message de la marque"
  }
},

impressum

Country specific fields

free_text: Free text field containing impressum informations saved as an HTML string.

"impressum": {
  "free_text": {
    "default": "<p>An impressum</p>",
    "DE": "<p>An impressum for germany</p>"
  }
},

Full JSON Example

for a full JSON example click here

Introduction​

API Design​

POST: /api/v2/products/{product_id}/elabel/​

GET: /api/v2/products/{product_id}/elabel/​

Generic Fields​

Section Objects​

Fallback behaviour:​

System keys​

product-infos​

ingredients​

serving-infos​

nutrition​

responsible-consumption​

sustainability​

geographical-indications​

business-operator​

brand-info​

impressum​

Full JSON Example​

Introduction

API Design

POST: /api/v2/products/{product_id}/elabel/

GET: /api/v2/products/{product_id}/elabel/

Generic Fields

Section Objects

Fallback behaviour:

System keys

product-infos

ingredients

serving-infos

nutrition

responsible-consumption

sustainability

geographical-indications

business-operator

brand-info

impressum

Full JSON Example