Add-ons
Add-ons are modifier groups attached to a product (milk choice on a coffee, sauce on a bowl). Each group has options, a selection mode (single / multiple), and an optional `is_required` flag. Add-ons are surfaced inline on the product detail response and via a dedicated endpoint when you only need the modifier shape.
GET /api/v1/catalogue/products/{product_id}/add-ons
Return only the modifier groups attached to a product.
Request
curl https://api.cimplify.io/api/v1/catalogue/products/prod_abc123/add-ons \
-H "X-Public-Key: pk_test_your_publishable_key"Response
{
"success": true,
"data": [
{
"id": "addon_milk",
"name": "Milk choice",
"selection_type": "single",
"is_required": false,
"min_selections": 0,
"max_selections": 1,
"options": [
{ "id": "opt_oat", "name": "Oat milk", "price": "0.50" },
{ "id": "opt_almond", "name": "Almond milk", "price": "0.50" },
{ "id": "opt_skim", "name": "Skim milk", "price": "0.00" }
]
},
{
"id": "addon_extras",
"name": "Extras",
"selection_type": "multiple",
"is_required": false,
"min_selections": 0,
"max_selections": 3,
"options": [
{ "id": "opt_shot", "name": "Extra shot", "price": "1.00" },
{ "id": "opt_syrup", "name": "Syrup", "price": "0.50" }
]
}
]
}Add-on object
| Field | Type | Description |
|---|---|---|
id | string | Modifier group identifier. |
name | string | Display name for the group. |
selection_type | string | single (radio) or multiple (checkbox). |
is_required | boolean | Whether the customer must pick at least one option. |
min_selections | int | Minimum number of options required. |
max_selections | int | Maximum number of options allowed. |
options | array | Each option has id, name, price. |
Selecting add-ons in the cart
Pass the chosen option IDs as add_on_options on POST /cart/items. The server validates them against the modifier group rules and rejects invalid combinations with 400 VALIDATION_ERROR.
curl -X POST https://api.cimplify.io/api/v1/cart/items \
-H "X-Public-Key: pk_test_your_publishable_key" \
-H "Content-Type: application/json" \
-d '{
"item_id": "prod_abc123",
"quantity": 1,
"variant_id": "var_double",
"add_on_options": ["opt_oat", "opt_shot"]
}'Composites
Composites are build-your-own products: pizzas, salad bowls, PC builders. Each composite exposes one or more `component groups` with pricing and selection rules. Use `calculate-price` to preview the total before adding to cart.
Cart
The cart is server-owned and bound to the caller’s session. Items are added by `item_id` with an optional `variant_id` and add-on selections. The same cart is read on the storefront and on checkout; there is no client-side cart sync.