Maintaining your product catalog through the API
After reading this article you can create, update and sync your complete product catalog — products, prices, categories, recipes and packages — from your own system through the API instead of importing spreadsheets.
If your product catalog lives in another system (merchandise management, ERP, recipe software), the /api/v1/products endpoints keep it in sync with Univents. Your system sends the products, Univents creates or updates them — with the same rules as the inventory: gross/net price, standard VAT rate, purchase price per packaging, inherited allergens and automatic package prices.
Every field, its type and its allowed values are listed in the API reference at https://univents.app/api/v1/docs (section products, schema Product).
Key and permission
Create a key under Integrations → Developer → API keys with Read products & categories and Write products, categories & recipes. Writing does not include reading — pick both if your system also queries. The setup is described in the article on API keys.
Your own identifier: external_id
Send the number from your system as external_id. It is unique within your workspace; a second product with the same identifier is rejected. That way you never need to store our internal IDs. When a product is deleted, its identifier is free again.
Creating a product
curl -X POST https://univents.app/api/v1/products \
-H "Authorization: Bearer rv_live_…" \
-H "Content-Type: application/json" \
-d '{"name":"Farmhouse bread","external_id":"ERP-1001","sku":"BR-1","price_gross":4.28,"tax_rate":7,"alt_unit_name":"loaf","category_name":"Bread","allergens":["gluten"]}'
Without tax_rate your workspace standard rate applies. Set the category with category_id or category_name — an unknown name creates the category.
Prices: one side leads
Send either price_net or price_gross. The side you send leads (price_basis) and Univents derives the other one with the VAT rate. Both together are rejected, so no side is ever silently lost. If you later change only the VAT rate, the leading side stays and the other is recalculated.
Syncing many products at once
POST /api/v1/products/batch takes up to 500 products per call:
curl -X POST https://univents.app/api/v1/products/batch \
-H "Authorization: Bearer rv_live_…" \
-H "Content-Type: application/json" \
-d '{"rows":[{"external_id":"ERP-1001","price_gross":4.48},{"external_id":"ERP-1002","sku":"FLOUR-405","name":"Wheat flour 405","price_net":0.89,"alt_unit_name":"kg"}]}'
This is how Univents finds the matching product for each row:
id, if you send it,- otherwise
external_id— unknown means: create, - otherwise
sku, but only if exactly one product has that article number, - otherwise the product is created (
nameis required then).
A row without id, external_id and sku is rejected, so a retry never creates duplicates. On the first sync with external_id and sku, Univents links your identifier to the existing product with that article number.
What gets overwritten: fields you send overwrite the stored value. Fields you leave out stay unchanged. null clears a field.
Description: description is plain text. When you send it (on create, update or in a sync), it replaces the description formatted in the inventory: the formatting is dropped, and the inventory, booking pages and documents show exactly your text. Each line break (\n) becomes its own paragraph in the inventory.
The response lists created, updated or error for each row, with the reason and field names. A faulty row does not stop the others. With "dry_run": true you check a sync without writing anything. If two rows point to the same product (say once by identifier, once by article number), only the first applies. A batch counts as one request towards the limit of 120 requests per minute; on top of that, at most 6 batch calls per minute and key are possible (3,000 products). Article numbers and identifiers may contain any character, including inch marks such as Monitor 24", HDMI.
Recipes and packages
PUT /api/v1/products/{id}/components replaces the complete ingredient or content list of a product:
curl -X PUT https://univents.app/api/v1/products/<id>/components \
-H "Authorization: Bearer rv_live_…" \
-H "Content-Type: application/json" \
-d '{"components":[{"child_external_id":"ERP-2001","quantity_per_parent":0.5},{"child_sku":"SALT-1","content_quantity":10}]}'
Each row references a product of your workspace with exactly one of child_product_id, child_external_id or child_sku. The amount is in the ingredient’s unit (quantity_per_parent) or in its content per unit (content_quantity, e.g. 200 ml from a 1 l bottle). The list is replaced completely or not at all; if an ingredient already contains this product, the call is rejected. Univents recalculates automatic prices, purchase prices and allergens afterwards. If a plain product (type physical_product, neither package, recipe nor rental) gets at least one component this way, it automatically becomes a package (is_bundle) — just like in the inventory when you add the first component. The response reports this with promoted_to_bundle. Recipes, packages, rental items and services keep their type, and an empty list does not change the type. To make the product a recipe, set is_kitchen_produced on the product. A product the API created without product_type and without components is a service and stays one here — send "product_type":"physical_product" with it if it should become a package.
The easiest way to create a package is one call: send the components right when you create the product (POST /api/v1/products or a batch row), in the same format as above:
curl -X POST https://univents.app/api/v1/products \
-H "Authorization: Bearer rv_live_…" \
-H "Content-Type: application/json" \
-d '{"name":"BBQ package","external_id":"ERP-3001","components":[{"child_external_id":"ERP-2001","quantity_per_parent":2}]}'
If product_type is missing and at least one component is included, Univents creates the product as a physical product and it becomes a package. If you send product_type, exactly that type stays — service included. The components are checked before anything is saved; if they cannot be saved, the product is not created either. In a batch, components may point to products created by an earlier row of the same call (not a later one), and "dry_run": true checks the components too. If a batch row brings components for a product that already exists, it replaces its list like the call above, without changing the type.
Categories and locations
/api/v1/product-categoriescreates, renames and deletes catalog categories. Products of a deleted category move to the fallback category; the fallback category itself cannot be deleted.PUT /api/v1/products/{id}/locationssets at which locations a product is offered (available) or booked automatically (required).
Fetching changes
GET /api/v1/products?updated_since=… returns every product changed since a point in time, page by page with cursor. You can also filter by external_id, sku or category_id. Deleted products come with include_deleted=true.
What the API does not cover (yet)
Images, variants, price groups, prices from a future date, additional suppliers per product and ticket quotas are still maintained in the inventory. Fields Univents calculates itself (such as inherited allergens) are readable but not writable — sending them returns an error naming the field.