Data model

Adding a property to a product on revenexx is not a migration. It is a row in attributes and a row in family_attributes. Six entities describe the whole shape of a tenant's catalog, and every one of them is ordinary tenant data a merchant can change.

The active flag works the same on these six entities (attribute_groups, attributes, attribute_options, families, family_variants and measurement_families):

• Write. active is an optional boolean on POST and PUT, default true. Send false to make an entry inactive. Anything that is not a boolean answers 400 invalid_active.
• Read. A list returns active and inactive entries unless you filter. Use ?active=true for a picker.
• Existing records. Records that already carry an inactive entry keep it. A write cannot newly assign one (409 entry_inactive).

Attributes

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

type and entity_type deliberately carry no fixed value list. A tenant or integrator can add a type; GET /v1/products/attribute-schema maps an unknown one onto a text field rather than refusing to answer.

Attribute groups

A group is a section of the product form, not just a label. code is what a resolved field carries as its group, labels is the heading a person sees, and position orders the sections ascending.

Attribute options

The permitted values of a select or multi-select.

{
  "attribute_id": "…",
  "code": "matte_black",
  "labels": { "en": "Matte black", "de": "Mattschwarz" },
  "position": 20,
  "swatch": { "hex": "#1b1b1b" }
}

Label keys follow the tenant's locale policy: de and en in a tenant that keeps text per language, as in these examples, de-DE and en-GB in one that keeps text per region. See Languages and locale codes.

code is what gets stored in the product's attribute_values — never the label. Two tenants may label the same code differently. Deleting the attribute deletes its options with it. Options that tie on position keep whatever order the database returned, so give every option a position if the order matters.

Families

A family answers which attributes does a product of this kind have.

A product's name being per-family is the reason POST /v1/products/labels exists: no plain read can answer what a product is called.

Family attributes

One row per (family, attribute). This is the link that makes an attribute part of a family's form.

Deleting either side deletes the link.

Family variants

How a family splits — not which product splits. A family may carry several structures, and a product names the one it follows through family_variant_id.

axes names the attribute codes the split happens on, and two shapes are in the wild; both are read:

{ "code": "shoes_by_colour_size", "axes": ["colour", "size"] }

{
  "code": "shoes_by_colour_size",
  "axes": [
    { "level": 1, "axes": ["colour"] },
    { "level": 2, "axes": ["size"] }
  ]
}

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.

Measurement families

The unit set a measure attribute offers.

{
  "code": "weight",
  "standard_unit": "KILOGRAM",
  "units": [
    { "code": "KILOGRAM", "symbol": "kg", "convert_factor": 1 },
    { "code": "GRAM", "symbol": "g", "convert_factor": 0.001 }
  ],
  "labels": { "en": "Weight" }
}

convert_factor multiplies a value into standard_unit, so a gram is 0.001 kilograms. Every value is converted to the standard unit before it is compared or sorted. symbol is what a form prints next to the number.

List and create

Every list is paged with limit and offset, and reports page.total. Every column of the entity is an exact-match query parameter, order sorts by one column, and a query key that is not a column is refused with 400 (unknown_filter). The API reference still says that such a key is dropped; the API refuses it, as described here.

Every create answers 201 with the stored row, including its id. A body whose active is not true or false answers 400 (invalid_active), on every entity here but family_attributes.

Read, change or delete one entry

Attribute groups, attributes, attribute options, family attributes, measurement families, families and family variants each have three routes on {id}:

• GET returns the whole row as stored.
• PUT is a partial patch: it names only the columns to change, and every column it leaves out keeps its value. A body that names no column answers 400, and so does an active that is not true or false (invalid_active, on every entity here but family_attributes). On an attribute, a family attribute or a family, pointing the row at an inactive entry it did not point at before answers 409 entry_inactive.
• Locale keys. On every entity here but family_attributes, a locale key in labels that is not one of the tenant's write keys answers 422 (unknown_locale, ambiguous_locale, invalid_locale, or duplicate_locale when two spellings of one key carry different values).
• DELETE is a hard delete: the row is gone, with no trash and no restore. To take an entry out of use and keep it, set active to false instead.
• Unknown id. An unknown id answers 404, and so does another tenant's id.

The table below lists every cascade for each entity: a delete changes nothing beyond what its row names. Products store attribute and option codes inside attribute_values, not ids, so a value already stored under a deleted attribute or option stays as it is.

Seed the base model

curl -X POST https://api.revenexx.com/v1/products/defaults \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..." \
  -H "Content-Type: application/json" \
  -d '{}'

POST /v1/products/defaults creates the smallest catalog model a tenant can work with, for a tenant that has none: the attributes name (text, localizable), description (textarea, localizable) and images (asset_collection), and the family standard carrying all three, with name as its label attribute and required, and images as its image attribute. Every attribute and family the seed writes carries metadata.seeded_by: "products.defaults", and that mark is how a run tells its own rows from the tenant's. The model is created without a market.

• Any attribute or family without the mark (one the tenant created): the answer is seeded: false with reason: not_empty, and nothing is written.
• No attribute or family at all, or only marked ones: the run creates whatever of the model is missing. So a run that stopped half-way is finished by the next one.
• The whole model already in place: nothing is written, and the answer is seeded: false with reason: already_seeded. That makes the call idempotent.

The answer lists the attribute codes the run created, the family code if it created the family, and how many attributes it assigned.

Read the shape in one call

Six entities is five reads and a join. Do not do that — GET /v1/products/attribute-schema answers one ready-to-render field list, ordered by group then by the family's own ordering, with the storage path and fallback order per field. See Completeness.

Where to go next

• Model a catalog with attributes, families and variants — the walkthrough: decide the model, build it over the API and repair a flat import.
• Products — the row these definitions shape.
• Completeness — attribute-schema and the completeness measure.
• References — where a reference_entity attribute draws its values from.
• Assets — asset families and their attributes.