Product steps

Product steps describe the configurator flow for one product. They control order, labels, translations, layout, selection rules, attached options, and validation readiness.

Recommended workflow

Order	Action	Endpoint
1	Create brands, categories, and a product.	`/v1/brands`, `/v1/categories`, `/v1/products`
2	Create reusable options.	`POST /v1/options`
3	Create product steps and attach option ids.	`POST /v1/products/{product_id}/steps`
4	Replace step attachments when options change.	`PUT /v1/products/{product_id}/steps/{step_id}/options`
5	Validate the product configuration before activation or tenant handoff.	`GET /v1/products/{product_id}/configuration/validation`

Endpoints

Method	Path	Use
POST	`/v1/products/{product_id}/steps`	Create a step for a tenant product.
GET	`/v1/products/{product_id}/steps`	List steps. Supports `active`.
GET	`/v1/products/{product_id}/steps/{step_id}`	Read one step.
PATCH	`/v1/products/{product_id}/steps/{step_id}`	Update provided step fields.
PUT	`/v1/products/{product_id}/steps/{step_id}/options`	Replace the option attachments.
DELETE	`/v1/products/{product_id}/steps/{step_id}`	Deactivate a step.
GET	`/v1/products/{product_id}/configuration/validation`	Return a validation report for the product configuration.

Create step example

curl -X POST https://api.fenestro.io/v1/products/42/steps \
  -H "Authorization: Bearer fen_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Choose the colour",
    "name_en": "Choose the colour",
    "type": "selection",
    "content_type": "couleurs",
    "display_order": 1,
    "required": true,
    "skippable": false,
    "layout_type": "grid",
    "display_columns": 4,
    "display_price": true,
    "display_images": true,
    "options_min": 1,
    "options_max": 1,
    "option_ids": [101, 102, 103],
    "translations": {
      "de": { "name": "Farbe auswählen" }
    }
  }'

Attach options example

curl -X PUT https://api.fenestro.io/v1/products/42/steps/8/options \
  -H "Authorization: Bearer fen_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "option_ids": [101, 102, 103, 104] }'

Replacing attachments preserves the other keys already present in content_configuration. Only the option list is replaced. This keeps existing configurator JSON compatible with the storefront.

Validation report

curl https://api.fenestro.io/v1/products/42/configuration/validation \
  -H "Authorization: Bearer fen_live_xxxxxxxxxxxx"

The report returns valid, errors, and warnings. Validation checks tenant ownership, active category and brand, active steps, duplicate step ordering, invalid JSON, missing required options, inactive options, invalid next/previous step references, and option ids from another tenant.

Important fields

Field	Notes
`type`	Required step kind, for example `selection`, `dimension`, `checkbox`, or a tenant-specific type.
`content_type`	Optional option/content family used by the configurator, for example `couleurs` or `ouvertures`.
`option_ids`	Public option identifiers from `/v1/options`. Every id must be active and tenant-owned.
`content_configuration`	Optional JSON for advanced configurator data. The API stores it and expands option attachments into its `options` list.
`options_min`, `options_max`	Selection bounds. `options_min` must be lower than or equal to `options_max`.
`translations`	Optional JSON object for localized labels/descriptions.

Common step errors

Error	Meaning
`not_found`	The product or step does not exist for the authenticated tenant.
`invalid_option`	At least one `option_id` is missing, inactive, or belongs to another tenant.
`duplicate_display_order`	Another active step already uses the same `display_order` for the product.
`validation_error`	The request body is missing required fields or violates field limits.