Configurators

The Configurator object — controls, calculations, parts and presets — how a configurator prices a product, test calculations, and the public showcase of shareable configurators.

A configurator is a pricing engine for one kind of product. The customer fills in controls (width, fabric, colour), and calculations turn those values into quantities of materials, i.e. a priced bill of materials. Parts optionally produce a production cut-list, and presets are ready-made configurations.

A configurator is what the widget shows to customers. A priced result saved to an order becomes a product.

The structure is stored as JSON and is not validated beyond formula syntax. A misspelled field does not cause an error; the line it belongs to simply prices at 0. Always check a configurator with Calculate Configurator and read its warnings.

Field types follow the field notation.

Access

Project endpoints require both the projects and configurators OAuth scopes. The user must be a member of the project, and the owner's subscription must be active. Otherwise they return 404 RES_NOT_FOUND. The project owner bypasses permission checks.

Material prices inside a configurator follow the material price permissions: a tier the user may not see is returned as 0.

Showcase endpoints require only the configurators scope, except copying, which also needs projects.

Configurator Object

Configurator Structure

Prices are rounded to the project's price_step: material lines to cents, totals to the step.

Control Structure

{
  "id": "$width",
  "type": "number",
  "label": "Width, mm",
  "default": 550,
  "value": "",
  "class": "col-span-6",
  "source": "",
  "dataset": "",
  "order": 1,
  "min": 150,
  "max": 2500,
  "step": 1
}

A materials control is billed directly from its value and needs no calculation entry.

Calculation Structure

One calculation produces at most one line of the bill of materials.

{
  "material": "Fabric",
  "formulas": [
    {
      "code": "$width * (max(1400, $height) + 200) / 1000000",
      "variable": "$cloth",
      "conditions": []
    }
  ]
}

Formula Structure

There is no OR between conditions. To express OR, repeat the formula with different conditions; the first match wins.

Condition Structure

Part Structure

A cut-list row. Parts never affect the price.

{
  "material": "<material uuid>",
  "formulas": [
    {
      "sizes": 2,
      "code": [
        "$width - 43",
        "$height",
        ""
      ],
      "unit": "mm",
      "item": {
        "quantity": 1,
        "unit": "pcs"
      },
      "conditions": []
    }
  ]
}

Preset Structure

Formulas

Formulas use a dedicated expression language, not JavaScript:

• Arithmetic + - * / % **, comparisons (== is loose, === strict), && || ?? !, ? :.
• Functions: abs round ceil floor trunc max min pow sqrt exp log log10 sin cos tan asin acos atan atan2 random lower upper trim. Constants: PI E LN2 LN10 SQRT2 SQRT1_2. There is no property access and no Math. prefix.
• $id is replaced by the control's value. Values from the form can be strings, so "1200" + 1 concatenates; write +$width + 1.
• A $id that matches no control makes the whole formula evaluate to 0. It does not cause an error; it shows up in warnings.

Units are never converted. Controls are usually in millimetres and prices per square or running metre, so divide: ($width / 1000) * ($height / 1000) for m².

Every formula and the product name template are parsed when saved. One that fails to parse rejects the request with 400 CONFIGURATOR_FORMULA_INVALID, see Errors.

Product name template

product_name is text with two kinds of placeholders. A bare $control is substituted as is, and a ${...} block is evaluated as an expression. An untouched control reads as the literal [none].

${'$system' == 'Uni' ? 'Closed PVC' : '$system'}; fabric - ${lower('$cloth')}; $width×$height mm

Price

sale total     = Σ(quantity × (1 + percent_waste/100) × sale_price × price_multiplier) + product_work_cost + product_amortization
dealer total   = same with dealer_price
purchase total = Σ(quantity × (1 + percent_waste/100) × purchase_price × price_multiplier)

List Configurators

GET /api/v1/projects/{project.uuid}/configurators

Returns the project's configurators, most recently updated first, without the structure fields (controls, calculations, parts, presets), prices and materials.

Requires can_view_configurators.

Query String Params

Get Configurator

GET /api/v1/projects/{project.uuid}/configurators/{configurator.uuid}

Returns the full configurator, including its linked materials.

Requires can_view_configurators.

Create Configurator

POST /api/v1/projects/{project.uuid}/configurators

Requires can_edit_configurators.

JSON Params

Create the materials first, then the configurator with all of them in material_uuids.

Example Request

{
  "name": "Roller blind",
  "product_name": "Roller blind $cloth, $width×$height mm",
  "is_shareable": false,
  "controls": [
    {
      "id": "$width",
      "type": "number",
      "label": "Width, mm",
      "default": 550,
      "value": "",
      "class": "col-span-6",
      "source": "",
      "dataset": "",
      "order": 1,
      "min": 150,
      "max": 2500,
      "step": 1
    },
    {
      "id": "$height",
      "type": "number",
      "label": "Height, mm",
      "default": 1400,
      "value": "",
      "class": "col-span-6",
      "source": "",
      "dataset": "",
      "order": 2,
      "min": 150,
      "max": 2600,
      "step": 1
    },
    {
      "id": "$cloth",
      "type": "select",
      "label": "Fabric",
      "default": "Blackout 605",
      "value": "",
      "class": "col-span-12",
      "source": "group",
      "dataset": "Fabric",
      "order": 3
    }
  ],
  "calculations": [
    {
      "material": "Fabric",
      "formulas": [
        {
          "code": "$width * (max(1400, $height) + 200) / 1000000",
          "variable": "$cloth",
          "conditions": []
        }
      ]
    },
    {
      "material": "0199a2c1-5d6e-7f70-8182-93a4b5c6d7e8",
      "formulas": [
        {
          "code": "$width / 1000",
          "variable": "",
          "conditions": []
        }
      ]
    }
  ],
  "material_uuids": [
    "0199a2c0-7a1b-7c2d-8e3f-a0b1c2d3e4f5",
    "0199a2c1-5d6e-7f70-8182-93a4b5c6d7e8"
  ]
}

Response

201 Created

{
  "uuid": "0199ab16-3d4e-7f50-8162-738495061728"
}

Modify Configurator

PATCH /api/v1/projects/{project.uuid}/configurators/{configurator.uuid}

Updates only the fields you send. controls, calculations, parts, presets and material_uuids each replace the whole list when sent. At least one field must be present. Only the formulas you send are validated.

On update, price_multiplier below 1 is silently replaced with 1.

Requires can_edit_configurators.

Response

204 No Content

Replace Configurator

PUT /api/v1/projects/{project.uuid}/configurators/{configurator.uuid}

Same as Modify Configurator, but every field of Create Configurator is required. image_uuid may be null.

Delete Configurator

DELETE /api/v1/projects/{project.uuid}/configurators/{configurator.uuid}

Deletes the configurator. Its materials and the products already made with it stay.

Requires can_edit_configurators.

Response

204 No Content

Calculate Configurator

POST /api/v1/projects/{project.uuid}/configurators/{configurator.uuid}/calculate

Runs the saved configurator with the given control values and returns the priced result. Price tiers the user's role may not see (can_view_purchase_price, can_view_dealer_price, can_view_sale_price) count as 0 in every line and total. Nothing is written. Use it to test a configurator after changing it.

Requires can_view_configurators.

JSON Params

Example Request

For a configurator with only the fabric line from the example above:

{
  "values": {
    "$width": 1200,
    "$height": 1600,
    "$cloth": "Blackout 605"
  }
}

Response

200 OK

A calculated_materials line:

{
  "product_name": "Roller blind Blackout 605, 1200×1600 mm",
  "price_totals": {
    "purchase": 9.53,
    "sale": 22.45,
    "dealer": 17.01
  },
  "calculated_materials": [
    {
      "uuid": "0199a2c0-7a1b-7c2d-8e3f-a0b1c2d3e4f5",
      "name": "Blackout 605",
      "unit": "sm",
      "quantity": "2.268",
      "price": {
        "purchase": 4.2,
        "sale": 9.9,
        "dealer": 7.5
      },
      "amount": {
        "purchase": 9.53,
        "sale": 22.45,
        "dealer": 17.01
      }
    }
  ],
  "calculated_parts": [],
  "warnings": []
}

Showcase

Configurators with is_shareable: true and status: active, from all Configo projects, form a public catalog. Any user can browse it and copy a configurator into their own project. Prices are never exposed through the showcase.

List Showcase Configurators

GET /api/v1/showcase/configurators

Requires the configurators scope.

Query String Params

Response

200 OK — an array of {uuid, name, product_name, product_unit, is_calculations_displayed, updated_at}, most recently updated first.

Get Showcase Configurator

GET /api/v1/showcase/configurators/{configurator.uuid}

Returns the configurator's structure and materials. All prices, product_work_cost, product_amortization and price_multiplier are 0.

Requires the configurators scope.

Copy Showcase Configurator

POST /api/v1/showcase/configurators/{configurator.uuid}/copy

Copies the configurator and all its materials into one of the user's projects. The copy is named "<name> [showcase]", is not shareable, and gets new material uuids that calculations are remapped to. Prices are copied only if the user is also a member of the source project; otherwise they are 0.

Requires the projects and configurators scopes, and can_edit_configurators in the target project.

JSON Params

Response

201 Created

{
  "uuid": "0199ab27-4e5f-7061-8273-849506172839"
}

Errors

CONFIGURATOR_FORMULA_INVALID lists every problem in reason:

{
  "id": 4013,
  "code": "CONFIGURATOR_FORMULA_INVALID",
  "message": "A configurator formula or the product name template could not be parsed.",
  "reason": [
    "calculations[0].formulas[0]: Expected \")\"",
    "product_name: Unexpected character: ."
  ]
}