POST
Create a bundle
Company space For: Manager · Permission: bundles.create Conditions
  • title, prices (at least one) and components (at least two) are required.
  • Each component must be an active product-variant item of the organization, listed once, with an active unit that belongs to that item and a quantity of at least 1.
  • The handle must be unique within the company, counting every bundle of the company. When omitted it is generated from the title.
  • sku and barcode, when sent, must be unique among all units of sale of the organization.
  • Each price needs a name (stored trimmed and lowercase) and an amount in major units with at most the currency’s decimals; price names must be distinct within the bundle and so must price amounts.
  • category_id, when sent, must be a category of the organization.
  • is_tracked, when sent, must be true: a bundle is always tracked in stock.
  • Sending tax fields (tax_configuration_mode, is_taxable, vat_rate_id) also needs the tax-assignment update permission on bundles, and the VAT rate must be valid for the company’s tax profile. tax_ids is not accepted here and is ignored.
  • image, when sent, must be an image of at most 2048 KB.
What else happens
  • Creates the bundle, its item (status draft unless status is sent, purpose goods, tracked), its single unit in the built-in bundle unit of measure, its prices and its components.
  • Stores the uploaded image in public file storage; the file is deleted again when the creation fails.
  • Writes the tax configuration of the bundle when tax fields are sent.
Part of Sell bundles and kits.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

response
enum<string>
default:none

Response mode. Default none; none answers 204 No Content.

Available options:
none,
resource
fields
string

Comma-separated JSON keys of the root resource (id is always rendered). Available: vat_rate_id, tax_configuration_mode, category_id, id, stockable_id, title, handle, description, status, image_url, sku, is_taxable, components_count, created_at, updated_at.

include
string

Comma-separated include paths, each optionally followed by its fields in parentheses: units(id,sku),units.uomUnit(id,name). Max depth 6, max 40 paths. Available: vat_rate, taxes, units, units.uomUnit, units.prices, units.stockable, prices, inventoryItem, inventoryItem.stockable, inventoryItem.inventoryLevels, components, components.variant, components.stockableUnit.

Response

Resource (only with response=resource).

id

Identifier of the bundle (27-character KSUID string).

stockable_id

Identifier of the bundle's item, the stock and price record behind it.

title

Name of the bundle.

handle

Unique short name of the bundle within the company, used like a slug.

description

Free-text description; null when none.

status

Sale status of the bundle, read from its item: draft (not on sale), active (on sale) or archived (withdrawn and not editable).

image_url

Public URL of the bundle's image; null when it has none.

sku

Stock-keeping code of the bundle's unit; null when none was set. Present only when the bundle's units are loaded.

is_taxable
boolean | null

Whether tax applies to the bundle, from its tax configuration; null when it inherits the category setting. Present only when the item is loaded.

units
array

The bundle's units of sale (a bundle has a single one, in the built-in bundle unit of measure). Included only when requested.

prices
array

Prices of the bundle for the current company. Included only when requested.

inventory_item
object | null

Stock record of the bundle, null until a first assembly. Included only when requested.

components_count
integer

Number of components in the bundle's recipe. Present when counted.

components
array

The recipe of the bundle. Included only when requested.

created_at

Date and time the record was created (ISO 8601, UTC).

updated_at

Date and time the record was last changed (ISO 8601, UTC).

vat_rate_id

Identifier of the VAT rate set on the bundle; null when it uses the category's or the default rate.

tax_configuration_mode

inherit: the bundle follows its category's tax setting. custom: the bundle has its own taxable flag, VAT rate and taxes.

vat_rate
object | null

The VAT rate set on the bundle. Included only when requested.

taxes
array

Additional taxes assigned to the bundle. Included only when requested.

category_id

Identifier of the bundle's category; null when none.