Products

The products entity is the catalog itself. It is deliberately narrow: five meaningful columns plus one jsonb document that holds everything the merchant modelled.

curl "https://api.revenexx.com/v1/products?limit=20" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..."

The row

sku is the only column a create cannot omit. Two defaults are applied by the app rather than by the column: enabled comes from the tenant's new_products_enabled_by_default setting, so a client creating products through this route cannot publish twenty thousand unfinished products the moment it lands, and a product naming neither a family_id nor a family_variant_id gets the tenant's default_product_family. An explicit value in the body wins over both. A BMECAT import writes its products directly and applies neither default.

The variant hierarchy

• simple stands on its own.
• model carries the values its variants share. By convention it is not sold itself. The products API does not enforce that, so filter on kind wherever only sellable rows belong.
• variant carries the axis values and points at its model through parent_id.

Which attributes are the axes is declared per family by family_variants. An attribute named as an axis is set on each variant, not on the model. The attribute schema marks it read-only when you ask with kind=model, which is a hint to a form and not a rule of the API: a write of an axis value to a model is accepted.

attribute_values — four buckets

A product's properties are not columns. They are rows in attributes, selected per family by family_attributes, and their values live under the attribute code inside one of four buckets. The attribute's own localizable and scopable flags decide which:

{
  "common": { "net_weight": 2.4, "colour": "black" },
  "locale_specific": { "de": { "name": "Akku-Bohrschrauber" } },
  "channel_specific": { "b2b": { "minimum_order_quantity": 6 } },
  "channel_locale_specific": { "b2b": { "de": { "description": "…" } } }
}

The locale keys here are de because the example tenant keeps text per language. A tenant that keeps text per region writes de-DE. Never write de_DE: use the write key the tenant's locale policy names. See Languages and locale codes.

minimum_order_quantity here is only an example of a custom attribute. The platform stores it and returns it, but nothing in the cart or order flow enforces a minimum order quantity or a quantity step (as of 2026-10), so your storefront has to check it. What the platform does enforce is a ceiling, not a floor: max_items_per_cart and max_quantity_per_line on carts, and max_items_per_order on orders. A payment method's min_order_value is the only enforced minimum. It hides that payment method for a small order and does not reject the order.

Reading falls back. A reader takes the most specific bucket carrying the code, then locale, then channel, then common. common is always consulted last and always consulted, because early imports wrote everything there regardless of an attribute's flags — a reader that skips it reports an imported catalog as empty.

Do not re-derive that chain. GET /v1/products/attribute-schema answers, per field, the exact path a value belongs at and the full fallback order.

The value itself is whatever the attribute's type implies: a string, a number, a boolean, an option code for a select (never its label), a list of codes for a multi-select, {"amount": …, "unit": …} for a measure, a list of {"amount": …, "currency": …} for a price, an asset code for media.

{} is a normal state — a product nobody has enriched yet.

label is generated, and tells you when it is missing

label is maintained by the database so a grid of twenty thousand rows can sort and filter on a name without a join. It resolves the first of attribute_values.common.name, common.label, the name in the de-DE, en-US, de and en locale buckets, common.manufacturer_aid, and finally the SKU. Older data stored under de_DE or en_US is still read, after those, but no client should write those keys.

That order is fixed and does not follow the tenant's locale policy, so label is a sort and search helper, not the name to show a buyer. For display, read the name along the policy's read order for the locale you render.

So a value is always present — and a label equal to the SKU means the catalog holds no name for this product. Show it as a missing name, not as a name.

The grid

GET /v1/products answers SKUs and a jsonb blob. GET /v1/products/grid answers the list a person can scan: each row already flattened to its resolved display name, where that name came from, its family code, its stored completeness, and the value of every attribute marked usable_in_grid — no join, no second call.

curl "https://api.revenexx.com/v1/products/grid?q=bohr&enabled=true&limit=50" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..."

Two things to know:

• It filters on q, kind, enabled and family_id and nothing else. An unknown query parameter is refused with 400 rather than silently dropped. q is a case-insensitive substring of the stored label, which falls back to the SKU, so one box finds a product by either.
• The response's filters array reports the attributes marked is_filterable — that is what a filter bar should offer. It is not a query surface: filtering by attribute value is not offered by this API, because the values sit inside a four-bucket jsonb document behind a fallback chain.

Trashed products are excluded from the grid.

Two resolvers for other apps

POST /v1/products/batch answers id, sku, tax_class and the resolved display name for a list of ids and/or SKUs in one call. It exists for the app on the other side of a product reference — the prices app holds SKUs and needs a tax class, a feed builder holds ids and needs names — so neither pages through the catalog nor fires a request per line.

curl -X POST https://api.revenexx.com/v1/products/batch \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..." \
  -H "Content-Type: application/json" \
  -d '{"skus":["ACME-4711-BLK","ACME-4711-RED"]}'

It answers what it found: an identifier naming nothing is simply absent from items rather than an error. Compare what you sent with what came back if a miss matters.

POST /v1/products/labels answers what is this product called for up to 500 products at once, and reports where each name was found. source: "sku" means the catalog holds no name for it.

Writes

Creating from an existing product

POST /v1/products takes three more keys, all optional:

name is applied after copy_from, so it replaces the copied name in that locale.

curl -X POST https://api.revenexx.com/v1/products \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..." \
  -H "Content-Type: application/json" \
  -d '{"sku":"ACME-4712-18V","copy_from":"<PRODUCT_ID>","category_id":"<CATEGORY_ID>","name":"Akku-Bohrschrauber 18V"}'

• 404: copy_from or category_id names nothing. Nothing is created.
• 409, in_trash: the copy_from product or the category is in the trash, or a product in the trash holds the sku.
• 409, entry_inactive: the category is inactive, or the new product would carry an inactive family, family variant, manufacturer, option or reference record, copied ones included.

The checks above run before the product is written, so a refused call creates no product. The call is not atomic past that point: the product is written first and the category membership second. If filing it into the category fails, the call answers with an error but the product exists without that category; find it by its sku and file it with POST /v1/products/{id}/categories.

Per-product routes and the setup checklist

The four POST routes each work on one product; a bulk action in the app calls one of them once per product in the selection. All four answer 409 in_trash for a trashed product. GET /v1/products/setup is app-wide and takes no product id.

• Setup checklist. Answers 200 with { app, steps, done, total, complete }. Each step is { key, done, kind, optional }, where kind is auto (the app can check it) or manual (the app cannot check it, so it always reports done: false). A step is done when what it names exists: a live row of a table, or a setting with a value. done, total and complete count required steps only; optional steps are listed but do not count.
• Copy. Creates a copy under the new SKU and answers 201 with the new row and copied_parts. The name is always copied. The copy starts as a switched-off draft without a GTIN, release or completeness. attributes copies every value except files and images, images copies the file and image values, variants copies each variant with its attribute values (even without attributes in parts), and categories copies the hand-picked memberships. A variant's SKU is derived: the new SKU replaces the old prefix, otherwise it is <new>-<n>. Movement data and prices are not copied. Errors: 400 sku_required; 400 invalid_parts for a parts value outside the four; 409 sku_taken when the SKU or a derived variant SKU is taken; 409 in_trash when a product holding the SKU is in the trash. There is no transaction across rows: if a later step fails, what this call created is deleted again.
• Channels. Adds, removes or replaces the product's channel codes. The codes are stored as sent, trimmed and once each; they are not checked against the channels app. Errors: 400 invalid_channels when channels is not a list of strings; 400 invalid_mode when mode is not add, remove or replace.
• Manufacturer. Links the product to the manufacturer and copies its GPSR state onto the product. It does not create a manufacturer. It answers 404 for an unknown manufacturer, 409 in_trash for a trashed one, and 409 entry_inactive for an inactive one the product does not already carry. A plain PUT /v1/products/{id} with manufacturer_id also copies the GPSR state, but it does not answer 404 for an unknown manufacturer.
• Attribute value. Sets one attribute on one product and leaves the rest of its values as they are. With locale the value goes under that language; with all or no locale it goes into the common value, the same in every language. Errors: 400 when attribute or value is missing; 404 for an unknown product attribute code; 422 for a locale key the tenant does not write; 409 entry_inactive when the value names an inactive option or record.

Filters on the product list

GET /v1/products also filters on these, each as an exact match:

• status: draft, in_progress, in_review, released, phase_out or blocked. draft is the default on create. It sits beside enabled, which a shop still reads; the app does not derive one from the other. GET /v1/products/vocabularies/product-status serves the words.
• status_changed_at: set on create and on every status change. A write that names it has it dropped.
• channels: the whole list of channel codes, written in braces such as {webshop-de,punchout}. Order matters, and an empty list means no channel.
• channel_release: the whole per-channel release object, keyed by channel code. Null when the product is released as a whole.
• base_values: the whole commercial basics object (unit, gtin and the rest).
• manufacturer_gpsr_complete: true or false, copied from the manufacturer. Null without a manufacturer. Read-only.

Timestamps match exactly, with no ranges. channel_release and base_values compare the whole JSON document, so null cannot be matched; a value that is not valid JSON answers 400 invalid_value.

Trash and restore

Deleting a product sends it to the trash. A second delete of the same product deletes it for good, and so does emptying the trash. The platform also deletes trashed records that outlive the tenant's trash retention (90 days unless the tenant set another), except one that something still blocks.

The first delete fires product.trashed and a restore product.restored. product.deleted fires only once the record is deleted for good. See Deletes and the trash.

• Restore. POST /v1/products/{id}/restore brings the product back from the trash together with the variants of a model that went with it (the records that share its trash_batch). A record trashed on its own before stays in the trash. Everything that pointed at the product acts again as it did, because nothing was changed when it went. Restoring needs the same right as deleting. The answer lists every record that came back in restored.
• Refused with 409. not_in_trash when the product is not in the trash. parent_in_trash when the record it belongs to is in the trash in another group; details.restore names the call that brings that one back first.
• Refused with 404 when no product of this tenant has that id. A product of another tenant gets the same 404, not a 403.
• Empty the trash. POST /v1/products/trash/empty deletes the trashed products for good, oldest first, up to 200 per call, each through the same checks as a second DELETE.
• A record a blocker holds is listed in blocked with its reason and stays in the trash; the rest of the call goes on.
• deleted lists what this call removed for good. more: true means the call stopped at its limit and the trash may hold more: call it again.
• A storefront contact gets 403: emptying the trash is back-office work.

Reading and filtering the trash. GET /v1/products leaves trashed products out unless the call asks with trashed: only returns the trash alone, include returns the live and the trashed products together. Each product carries the fields below, and each one is also an exact-match filter on the list call. deleted_at and purge_at match only an exact timestamp; there is no range filter, so to see what was trashed in a period, sort with order and page.

The platform sets these fields when a product is deleted and clears them when it is restored, never through an update, so a client does not normally send them in a write.

The tax-class usage check

curl "https://api.revenexx.com/v1/products/tax-classes/reduced/usage" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..." \
  -H "X-Revenexx-Market: at"

A product names its tax class by code in tax_class, and a variant is a product row of its own, so it carries its own tax_class. Markets is the source of record for the rate, and it asks this route before it deletes a tax class: a count above zero stops the delete. Products in the trash count too, because a restore brings them back naming the class.

The answer carries in_use, count (capped at 1000), trashed (how many of those are in the trash) and samples (the first 20 by SKU, with id, code and name). count and samples are the field names every app's usage answer shares. A tax class is unique per market, so send X-Revenexx-Market to count only the products visible in that market: those assigned to it, plus the ones assigned to no market. A product has no market column; its market assignment is a scope (see Market-scopeable entities). Without the header every product of the tenant counts. Every code answers: one nobody points at is in_use: false, never a 404.

Where to go next

• Data model — the attributes, families and variant structures this row points at.
• Completeness — attribute-schema and the completeness measure.
• Categories — the tree and rule-driven membership.
• Import and export — loading a catalog in volume.
• Languages and locale codes — which key a translated value is stored under.