Kits and bundles

Use the kits API to read kit and bundle definitions, review their ordered components and assembly history, and manually assemble or disassemble kits.

The kit object

Field	Type	Description
`id`	string	Unique kit UUID.
`object`	string	Always `kit`.
`kit_number`	integer	Account-scoped kit number.
`item_id`	string	UUID of the assembled inventory item.
`item_number`	integer	Item number of the assembled inventory item.
`name`	string	Assembled item name.
`description`	string or null	Assembled item description.
`sku`	string or null	Assembled item SKU.
`barcode`	string or null	Assembled item barcode.
`category_id`	string or null	Assembled item category UUID.
`category_name`	string or null	Cached category label.
`quantity`	number	Current total assembled-item quantity.
`pieces`	integer	Number of component lines tracked by the kit.
`assembly_method`	string	`manual` or `automatic`.
`build_count`	number	Existing cumulative assembly counter.
`last_built_at`	string or null	Most recent assembly timestamp.
`created_at`	string or null	Creation timestamp.
`updated_at`	string or null	Last-modified timestamp.

The retrieve endpoint also includes components, ordered the same way as the SalesBinder kit definition.

Kit component fields

Field	Type	Description
`id`	string	Kit-component UUID.
`object`	string	Always `kit_component`.
`item_id`	string	Component inventory-item UUID.
`item_variation_id`	string or null	Selected variation UUID, when one is stored.
`name`	string or null	Component item name.
`sku`	string or null	Component item SKU.
`barcode`	string or null	Variation barcode when selected, otherwise the item barcode.
`quantity`	number	Component quantity required per kit.
`position`	integer	Stored component ordering weight.

Cost and price values are not included in kit responses.

List kits

GET/api/v3/kits

Required scope: kits:read

Returns active kit-backed items in the current account. The optional q parameter matches assembled-item name or SKU and also matches kit number when the value is numeric. Use assembly_method=manual or assembly_method=automatic to filter by assembly method. Standard page and limit pagination parameters are supported.

curl "https://yourbusiness.salesbinder.com/api/v3/kits?q=starter&assembly_method=manual" \
  --header "Authorization: Bearer YOUR_API_KEY"

Retrieve a kit

GET/api/v3/kits/{kit_id}

Required scope: kits:read

Returns one account-owned kit and its ordered component definition. A missing or cross-account UUID returns the standard resource_missing response.

curl "https://yourbusiness.salesbinder.com/api/v3/kits/98000000-0000-4000-8000-000000000301" \
  --header "Authorization: Bearer YOUR_API_KEY"

List assembly history

GET/api/v3/kits/{kit_id}/builds

Required scope: kits:read

Returns assembly history for one visible kit, newest first. Standard pagination is supported. location_id can restrict the result to one active account location, but it cannot expand the authenticated user's assigned-location access.

Kit build fields

Field	Type	Description
`id`	string	Assembly-history UUID.
`object`	string	Always `kit_build`.
`kit_id`	string	Parent kit UUID.
`location`	object or null	Compact location `id` and `name`; name is null when the historical location is unavailable.
`quantity`	number	Quantity assembled by this record.
`assembly_method`	string	`manual` or `automatic`.
`parent_kit`	object or null	Parent kit `id` and historical kit number for nested automatic assembly.
`user`	object	Compact user `id` and available display name.
`created_at`	string or null	Assembly timestamp.

The API does not expose a separate build-detail endpoint or kit-definition creation and editing.

Assemble a kit

POST/api/v3/kits/{kit_id}/builds

Required scope: kits:build

Creates one manual assembly and updates its components, nested kits, valuation, history, and inventory. Supply an active location_id and a positive quantity. SalesBinder assigns the current API user and the manual assembly method; fields such as user_id, automatic, kit_id, unit_cost, and parent-kit metadata are not accepted.

Use an Idempotency-Key when retrying this request so a network retry cannot create a second assembly.

curl --request POST \
  "https://yourbusiness.salesbinder.com/api/v3/kits/98000000-0000-4000-8000-000000000301/builds" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: assemble-starter-bundle-001" \
  --data '{
    "location_id": "98000000-0000-4000-8000-000000000011",
    "quantity": 2
  }'

The response is the stored kit_build object. SalesBinder prepares the required location assignments before validating available component inventory. Insufficient component stock or an invalid component definition returns 422 invalid_kit_build without creating a build.

Disassemble a stored assembly

DELETE/api/v3/kits/{kit_id}/builds/{build_id}

Required scope: kits:disassemble

Reverses the assembly's inventory changes and removes it from assembly history. The build must belong to the kit and account in the URL. A user assigned to one inventory location can disassemble only history from that location.

curl --request DELETE \
  "https://yourbusiness.salesbinder.com/api/v3/kits/98000000-0000-4000-8000-000000000301/builds/98000000-0000-4000-8000-000000000501" \
  --header "Authorization: Bearer YOUR_API_KEY"

Successful disassembly returns a narrow deletion object with id, object, kit_id, and deleted: true. The operation removes history, so a second request returns resource_missing.

Authorization behavior

Read endpoints require kits:read and the user's current inventory-list permission. Assembly and disassembly use independent kits:build and kits:disassemble scopes and require the user's current inventory-modification permission. Account and assigned-location boundaries are reapplied on every request.