Merging Ingredients

The ingredient merge feature allows you to consolidate duplicate ingredients into a single canonical entry. This is useful when the same ingredient exists under different names or has been created multiple times through integrations or manual entry.

There is a set of API endpoints for managing ingredients, including the merge, list merges, and revert endpoints.

What a merge does

When you merge a source ingredient into a target ingredient, the following happens by default:

• Stock items are matched between source and target based on package size (quantity + unit):
  • If no stock item with the same size exists on the target, the stock item is moved over from the source.
  • If a matching size already exists on the target, the stock items are merged — GTINs are appended and supplier packages are transferred.
• All recipes that use the source ingredient are updated to use the target ingredient, keeping all measurements intact.
• The source ingredient is archived.

The target ingredient's own data — allergens, nutritional values, carbon footprint, and other ingredient-level attributes — is never modified by a merge. Only stock items and supplier packages are moved.

Merge rules

• Multiple source ingredients can be merged into the same target over time.
• An ingredient that has been used as a source cannot be used as a source again in a new merge.
• An ingredient that has been used as a target cannot itself be merged into another ingredient.

Controlling merge behaviour

Both stock movement and recipe updates are enabled by default but can be disabled independently:

• Set move_stock=false to skip moving stock items.
• Set update_recipes_to_use_target_ingredient=false to leave recipes pointing at the source ingredient.
• Set archive_source_ingredient=false to keep the source ingredient active after the merge.

To merge only specific stock items, pass their IDs in stock_items_to_merge. To exclude specific stock items, use stock_items_not_to_merge. These two fields are mutually exclusive.

Reverting a merge

Every merge can be reverted using the Revert Ingredient Merge endpoint. By default, reverting a merge will:

• Unarchive the source ingredient.
• Move recipes back from the target to the source ingredient.
• Restore stock quantities to their pre-merge state.

Each of these can be disabled independently via the unarchive_source_ingredient, move_back_source_ingredient_to_recipes, and revert_stock parameters.

A reverted merge cannot be re-applied automatically — you would need to perform a new merge. Be aware that if time has passed since the original merge, stock may have been used or adjusted in the meantime, which can affect the accuracy of a stock reversion. Similarly, any manual edits made to recipes after the merge was performed will not be undone.

Tracking merges

Use the List Ingredient Merges endpoint to retrieve the full history of merge operations in your library. Results can be filtered by source ingredient, target ingredient, performing user, and reverted status.