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.

GET /api/v1/catalogue/composites

List composites. Supports limit.

cURL

curl "https://api.cimplify.io/api/v1/catalogue/composites?limit=20" \
  -H "X-Public-Key: pk_test_your_publishable_key"

GET /api/v1/catalogue/composites/{composite_id}

Composite detail with all component groups and selection rules.

cURL

curl https://api.cimplify.io/api/v1/catalogue/composites/comp_pizza \
  -H "X-Public-Key: pk_test_your_publishable_key"

Response

{
  "success": true,
  "data": {
    "id": "comp_pizza",
    "name": "Build-your-own pizza",
    "base_price": "8.00",
    "currency": "GHS",
    "groups": [
      {
        "id": "grp_size",
        "name": "Size",
        "min_selections": 1,
        "max_selections": 1,
        "components": [
          { "component_id": "size_small",  "name": "Small (10\")",  "price": "0.00" },
          { "component_id": "size_medium", "name": "Medium (12\")", "price": "2.00" },
          { "component_id": "size_large",  "name": "Large (14\")",  "price": "4.00" }
        ]
      },
      {
        "id": "grp_toppings",
        "name": "Toppings",
        "min_selections": 0,
        "max_selections": 5,
        "components": [
          { "component_id": "top_pepperoni", "name": "Pepperoni", "price": "1.50" },
          { "component_id": "top_mushroom",  "name": "Mushroom",  "price": "1.00" }
        ]
      }
    ]
  }
}

GET /api/v1/catalogue/composites/by-product/{product_id}

Resolve the composite definition that backs a product (when the product is itself the composite root).

cURL

curl https://api.cimplify.io/api/v1/catalogue/composites/by-product/prod_pizza \
  -H "X-Public-Key: pk_test_your_publishable_key"

POST /api/v1/catalogue/composites/{composite_id}/calculate-price

Quote the price of a specific composite configuration. Each entry in selections identifies a component, quantity, and optional variant or add-on option. location_id opts into location-specific pricing.

Body

cURL

curl -X POST https://api.cimplify.io/api/v1/catalogue/composites/comp_pizza/calculate-price \
  -H "X-Public-Key: pk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "selections": [
      { "component_id": "size_medium", "quantity": 1 },
      { "component_id": "top_pepperoni", "quantity": 1 },
      { "component_id": "top_mushroom", "quantity": 1 }
    ],
    "location_id": "loc_01H…"
  }'

Response

{
  "success": true,
  "data": {
    "composite_id": "comp_pizza",
    "base_price": "8.00",
    "components_total": "4.50",
    "subtotal": "12.50",
    "currency": "GHS"
  }
}

Errors

400 VALIDATION_ERROR: empty selections, blank component_id, or quantity below 1.
404 NOT_FOUND: composite or component doesn’t exist.

Adding a composite to cart

Pass the same selections through POST /cart/items as composite_selections.

cURL

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_pizza",
    "quantity": 1,
    "composite_selections": [
      { "component_id": "size_medium", "quantity": 1 },
      { "component_id": "top_pepperoni", "quantity": 1 }
    ]
  }'

Bundles Fixed combinations: the simpler sibling of composites.
Add-ons Modifier groups attached to standalone products.

Composites

On this page