Products

List products, retrieve by ID or slug, search, and get price quotes.

GET/api/v1/catalogue/products

List Products

Query Parameters

Parameter	Type	Description
`category`	string	Filter by category ID
`collection`	string	Filter by collection ID
`search`	string	Search term for name/description
`featured`	boolean	Only featured products
`limit`	integer	Items per page (default 20, max 100)
`page`	integer	Page number (default 1)

Example Request

curl

curl "https://storefront.cimplify.io/api/v1/catalogue/products?category=cat_1&limit=10" \
  -H "X-API-Key: pk_test_your_api_key"

Example Response

JSON

{
  "success": true,
  "data": [
    {
      "id": "prod_abc123",
      "name": "Espresso",
      "slug": "espresso",
      "description": "Rich double shot espresso",
      "category_id": "cat_1",
      "image_url": "https://cdn.example.com/espresso.jpg",
      "default_price": "4.50",
      "product_type": "product",
      "inventory_type": "none",
      "is_active": true
    }
  ],
  "meta": {
    "pagination": {
      "total_count": 42,
      "page_size": 10,
      "current_page": 1
    }
  }
}

GET/api/v1/catalogue/products/{id}

Get Product

Returns the full product with variants, add-ons, and images.

Example Response

JSON

{
  "success": true,
  "data": {
    "id": "prod_abc123",
    "name": "Espresso",
    "slug": "espresso",
    "description": "Rich double shot espresso",
    "category_id": "cat_1",
    "image_url": "https://cdn.example.com/espresso.jpg",
    "default_price": "4.50",
    "product_type": "product",
    "inventory_type": "none",
    "is_active": true,
    "variants": [
      {
        "id": "var_single",
        "name": "Single",
        "price_adjustment": "0.00",
        "is_default": true
      },
      {
        "id": "var_double",
        "name": "Double",
        "price_adjustment": "1.50",
        "is_default": false
      }
    ],
    "add_ons": [
      {
        "id": "addon_milk",
        "name": "Milk Choice",
        "selection_type": "single",
        "is_required": false,
        "options": [
          { "id": "opt_oat", "name": "Oat Milk", "price": "0.50" },
          { "id": "opt_almond", "name": "Almond Milk", "price": "0.50" }
        ]
      }
    ],
    "images": [
      { "url": "https://cdn.example.com/espresso.jpg", "is_primary": true }
    ]
  }
}

GET/api/v1/catalogue/products/slug/{slug}

Get Product by Slug

Same response shape as get-by-ID. Useful for SEO-friendly URLs.

Example Request

curl

curl https://storefront.cimplify.io/api/v1/catalogue/products/slug/espresso \
  -H "X-API-Key: pk_test_your_api_key"

POST/api/v1/catalogue/search

Search Products

Request Body

Field	Type	Description
`query`	string	Search query (required)
`limit`	integer	Max results (default 20)
`filters`	object	Optional filters (category, collection, etc.)

Example Request

curl

curl -X POST https://storefront.cimplify.io/api/v1/catalogue/search \
  -H "X-API-Key: pk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "espresso",
    "limit": 5,
    "filters": { "category": "cat_1" }
  }'

POST/api/v1/catalogue/quote

Get Price Quote

Calculates the final price for a product configuration including variant, add-ons, bundle/composite selections, and location-specific pricing.

Request Body

Field	Type	Description
`product_id`	string	Product ID (required)
`quantity`	integer	Quantity (default 1)
`variant_id`	string	Selected variant
`location_id`	string	Location for pricing
`add_on_option_ids`	string[]	Selected add-on option IDs
`bundle_selections`	object[]	Bundle component selections
`composite_selections`	object[]	Composite component selections

Example Request

curl

curl -X POST https://storefront.cimplify.io/api/v1/catalogue/quote \
  -H "X-API-Key: pk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_abc123",
    "variant_id": "var_double",
    "quantity": 2,
    "add_on_option_ids": ["opt_oat"]
  }'

Example Response

JSON

{
  "success": true,
  "data": {
    "quote_id": "qt_xyz789",
    "product_id": "prod_abc123",
    "unit_price": "6.50",
    "quantity": 2,
    "total": "13.00",
    "currency": "USD",
    "expires_at": "2025-01-15T11:00:00Z"
  }
}

POST/api/v1/catalogue/quote/refresh

Refresh Quote

Refreshes an existing quote with current pricing. Pass the same body as /quote plus the quote_id.

Product Object

Field	Type	Description
`id`	string	Unique product identifier
`name`	string	Product name
`slug`	string	URL-friendly identifier
`description`	string	Product description
`category_id`	string	Category reference
`image_url`	string	Primary image URL
`default_price`	string	Base price (decimal string)
`product_type`	string	product, service, digital, bundle, composite
`inventory_type`	string	none, tracked, variant_level
`is_active`	boolean	Whether product is active
`variants`	array	Product variants (on detail endpoint)
`add_ons`	array	Add-on groups (on detail endpoint)
`images`	array	All product images (on detail endpoint)