Product options
Option axes such as Size or Colour, their values, and the variant matrix they generate.
Option axes and the variant matrix they generate. The frozen option object and the plan payload are on Products and catalog.
List product options
/api/v1/kahunacart/products/{id}/options
The product's option axes with their values, its variants with the option-value combination each of them answers, and the widget names an axis can be rendered with. Call this before generate_variants so you know which axes and values exist.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Product id |
Add an option axis
/api/v1/kahunacart/products/{id}/options
Add an option axis to a product, for example Size or Colour, optionally with its values in the same call, and return the product's axes and variants. A product may have at most three axes; a fourth is refused with 422. Adding an axis does not create variants; call generate_variants for that.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Product id |
| name required | string | Axis name, for example Size or Colour |
| kind optional | string |
What this option is for. `variant` (the default, and everything written before product types) is an axis: picking a value picks a variant, and a product may have at most three. `addon` is an extra choice at the buy button — gift wrap, an engraving, a warranty — which never creates a variant, may be required, may use the text, textarea and checkbox widgets an axis cannot, and whose values may carry a price set through update_product's option_prices.
One of:
variant, addon |
| required optional | boolean | Only meaningful on an add-on. The shopper cannot add the product to their cart without answering it. A variant axis is already required, because a variant is a full combination or it is not a variant. |
| widget optional | string |
How the storefront renders the control. Swatches read the value colour; text, textarea and checkbox are add-ons only and have no values of their own, so they carry their price on the option.
One of:
dropdown, pills, swatches, text, textarea, checkbox |
| values optional | array of object | The values on this axis, created in the order given. Keys: `label`, `color` |
| translations optional | object | Language code to a map of field overrides for the axis name |
Update an option axis
/api/v1/kahunacart/products/{id}/options/{optionId}
Rename an axis, change how it is rendered, move it among the product's other axes, or replace its translation overrides. Returns the product's axes and variants. Only the fields sent are changed.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Product id |
| optionId required | integer | Option axis id |
| name optional | string | |
| widget optional | string |
One of:
dropdown, pills, swatches |
| position optional | integer | |
| translations optional | object |
Delete an option axis
/api/v1/kahunacart/products/{id}/options/{optionId}
Remove an axis from a product and return the axes and variants that remain. The variants stay: a Size by Colour product that loses Colour is a product with sizes, not a product with no variants. Combinations that now collapse onto each other are reported by the next generate_variants.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Product id |
| optionId required | integer | Option axis id |
Add an option value
/api/v1/kahunacart/products/{id}/options/{optionId}/values
Add one value to an option axis, for example Large on Size, and return the product's axes and variants. Adding a value does not create the variants it makes possible; call generate_variants for that.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Product id |
| optionId required | integer | Option axis id |
| label required | string | What the shopper reads, for example Large |
| color optional | string | "#rrggbb", used by the swatches widget |
| image_id optional | integer or null | A picture from this product's gallery, shown as the value's swatch and swapped into the gallery when a shopper picks it; null for none, and an image of another product is refused with 422 |
| translations optional | object |
Update an option value
/api/v1/kahunacart/products/{id}/options/{optionId}/values/{valueId}
Relabel a value, change its swatch colour, move it among the axis's other values, or replace its translation overrides. Returns the product's axes and variants.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Product id |
| optionId required | integer | Option axis id |
| valueId required | integer | Option value id |
| label optional | string | |
| color optional | string | "#rrggbb" |
| image_id optional | integer or null | A picture from this product's gallery; send null to clear it, and an image of another product is refused with 422 |
| position optional | integer | |
| translations optional | object |
Delete an option value
/api/v1/kahunacart/products/{id}/options/{optionId}/values/{valueId}
Remove one value from an axis and return the product's axes and variants. Every variant that named it keeps its row and loses that one answer, so a discontinued colour never silently deletes the stock sitting in it. Those variants come back as orphans in the next generate_variants plan and are removed with delete_variant.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Product id |
| optionId required | integer | Option axis id |
| valueId required | integer | Option value id |
Generate the variant matrix
/api/v1/kahunacart/products/{id}/options/generate
Work out which combinations of the product's option axes have no variant yet and report the plan: how many combinations there are in total, how many already exist, how many are missing and their labels, plus the orphan variants whose combination the axes no longer describe and the unassigned ones that answer no combination at all. This is a dry run unless you send apply true, and even then it only creates the missing combinations: it never deletes, so orphans are removed with delete_variant or, several at once, delete_variants. New variants inherit price, stock policy and weight from the product's default variant. Refused with 422 when the product has no axis with values.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Product id |
| apply optional | boolean |
Write the missing combinations; leave false to preview the plan
Default:
false |
Assign a variant to a combination
/api/v1/kahunacart/products/{id}/options/assign/{variantId}
Point one existing variant at one combination of option values, which is how a variant that predates the axes is adopted into the matrix instead of being deleted and retyped. Answers 409 when another variant of the same product already holds that combination.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Product id |
| variantId required | integer | Variant id |
| option_value_ids required | array of integer | One option value id per axis; an empty list clears the combination |
generate never deletes. It creates the combinations that have no variant and reports the ones the axes no longer describe under plan.orphans, for you to remove through the variant delete route. Assigning a combination another variant already holds is a 409.