Barcode Scanner

You can combine barcode‑based intakes with image recognition flows and user confirmations.

Plan & Token Requirements

Feature available in the following LogMeal Plans:

Accessible by the following User Types:

What It Does

Barcode Scanner lets you identify packaged foods by EAN/UPC barcode and either retrieve the mapped product, use that product as an ingredient of an existing food item, or create an intake for the current user.
Our product database includes millions of items across many countries and is periodically updated as new products appear.

When to Use It / Outcomes

• You want a fast lookup for packaged products without taking a photo.
• You need to add items to a food diary by scanning barcodes at the point of consumption.
• You want to use a packaged product as an ingredient of an existing recognized food item.
• You are building inventory or pantry flows that sync with user intakes.
• Output: Depending on the selected workflow, the API returns the matched dish/product information, the barcode product's dish id, or the imageId/occasion/userId of a newly created intake.

Feature-Specific Details

• Available workflows:

  • Lookup only → returns the dish id and product name from a barcode without creating an intake.
  • Use as an ingredient → use the dish_id returned by the lookup endpoint as barcodeClassId in /nutrition/confirm/ingredients. If no quantity is provided, the serving size stored from OpenFoodFacts is used by default.
  • Create intake → stores the barcode product as a new intake tied to the user and returns its identifiers.

• Input: barcode_id as an integer path parameter (e.g., 3029330022428).

• Localization: Product coverage spans multiple countries; names depend on product sources and may vary by region.

• Best paired with Ingredients/Nutrition features if you want per‑item nutrient breakdown after confirmation.

Sequence Diagrams

Product Lookup Flow

Use this flow when the app only needs to identify the packaged product without creating a new intake.

sequenceDiagram
  participant User
  participant App
  participant Food AI Engine API

  User->>App: Scan product barcode
  App->>Food AI Engine API: POST /v2/barcode_scan/{barcode_id} <br> (Authorization: APIUser token)
  Food AI Engine API-->>App: 200 OK (dish_id, product_name, barcode)
  App-->>User: Show matched product information

The lookup endpoint does not create an intake. The returned dish_id identifies the barcode product in LogMeal and can also be reused in other barcode workflows, such as adding the product as an ingredient.

Create Intake Flow

Use this flow when the scanned packaged product should be logged directly as a new food intake.

sequenceDiagram
  participant User
  participant App
  participant Food AI Engine API

  User->>App: Scan product barcode
  App->>Food AI Engine API: POST /v2/intake/barcode_scan/{barcode_id} <br> (Authorization: APIUser token)
  Food AI Engine API-->>App: 200 OK (imageId, occasion, userId, product information)
  App->>Food AI Engine API: GET /v2/intake/{imageId}
  Food AI Engine API-->>App: 200 OK (stored intake, recipe, nutritional information)
  App-->>User: Show saved barcode intake

This endpoint creates the intake directly. Unlike image-based food recognition, no dish-confirmation step is required because the recipe and nutritional information are obtained from the barcode product data.

Add Barcode Product as an Ingredient

Use this flow when the scanned packaged product should become an ingredient of an existing food item instead of being logged as an independent intake.

sequenceDiagram
  participant User
  participant App
  participant Food AI Engine API

  User->>App: Choose to add an ingredient
  User->>App: Scan product barcode
  App->>Food AI Engine API: POST /v2/barcode_scan/{barcode_id} <br> (Authorization: APIUser token)
  Food AI Engine API-->>App: 200 OK (dish_id, product_name)
  App->>App: Use dish_id as barcodeClassId
  App->>Food AI Engine API: POST /v2/nutrition/confirm/ingredients <br> (imageId, complete ingredient list + barcodeClassId)
  Food AI Engine API-->>App: 200 OK (ingredients confirmed and nutrition recalculated)
  App->>Food AI Engine API: GET /v2/intake/{imageId}
  Food AI Engine API-->>App: 200 OK (updated recipe and nutritional information)
  App-->>User: Show updated ingredients and nutrition

Using a Barcode Product as an Ingredient

Keep the following points in mind when implementing this flow:

• Use the lookup endpoint, not the intake endpoint. If the scanned product should be added as an ingredient, do not call POST /v2/intake/barcode_scan/<barcode_id>, as that endpoint creates a separate intake. Use POST /v2/barcode_scan/<barcode_id> instead.

• Use the returned dish_id as barcodeClassId. Pass this value when calling POST /v2/nutrition/confirm/ingredients.

• Send the complete ingredient list. The /v2/nutrition/confirm/ingredients endpoint updates the recipe of the affected food item rather than simply appending the new component. Existing ingredients that should remain in the recipe must therefore also be included in the request.

• A quantity is not required initially. If ingredientAmount is omitted for the barcode product, LogMeal uses the serving size stored from OpenFoodFacts as the default quantity:

  JSON

  {
    "barcodeClassId": 98765
  }

• The quantity can be changed later. Submit the same barcodeClassId with an explicit ingredientAmount in grams:

  JSON

  {
    "barcodeClassId": 98765,
    "ingredientAmount": 35
  }

• Refresh the intake after confirmation. Call GET /v2/intake/<imageId> to retrieve the updated recipe and recalculated nutritional information.

Related Endpoints

• POST /barcode_scan/{barcode_id} → 🔴 Scan & lookup a barcode and return dish id and product name.
• POST /intake/barcode_scan/{barcode_id} → 🔴 Scan & create a new intake for the user.
• POST /nutrition/confirm/ingredients → 🔴 🔵 Add a barcode product as an ingredient by passing the dish_id returned from /barcode_scan/<barcode_id> as barcodeClassId.
• GET /intake/{imageId} → ⚫ 🔴 🔵 Retrieve the complete intake after creating a barcode intake or modifying its ingredients.

Remember to check applicable request limitations inside each of the endpoints.

Related use case: Build a Unified Food Picker and Submit a Mixed Manual Intake shows how a resolved barcode product can be used either as a top-level barcode_food_item or as a nested barcode_ingredient in a mixed manual intake.

Choosing the Correct Barcode Flow

Choose the endpoint according to what the user intends to do with the scanned product:

For barcode ingredients, the app does not need to ask for a quantity immediately. When ingredientAmount is omitted, LogMeal uses the serving size stored from OpenFoodFacts. The user can change this quantity later.