Add a component to a kit/box product

Adds a component product to a kit product, specifying the quantity of the component required to build one kit unit. The parent product must have product_type: kit; supplying a non-kit parent returns code: not_a_kit. Duplicate component additions are rejected with code: component_already_exists. Requires products:write scope.

POST /products/{id}/components

Add a component to a kit/box product

cURL

curl --request POST \
  --url https://api.arcuserp.com/v1/products/{id}/components \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "component_product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "quantity_per_kit": 1,
  "sort_order": 0,
  "notes": "<string>",
  "external_source": "<string>",
  "external_id": "<string>",
  "migration_batch_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "imported_at": "2023-11-07T05:31:56Z"
}
'

201

{}

Authorizations

Authorization · string · header · required

API key issued per entity via Settings > Developers > API Keys. Each key carries scopes (e.g. orders:read, products:write). Bearer token format: Authorization: Bearer ark_live_ent_ Test keys use ark_test_ent_. Both are issued per entity via Settings > Developers > API Keys.

Headers

Idempotency-Key · string

Client-generated unique key for idempotent POST/PATCH/DELETE operations. Alias for the Idempotency parameter. Max 255 chars. On retry with the same key, the original response is returned without re-executing the operation. Keys expire after 24 hours.

Maximum string length: 255

Path Parameters

id · string<uuid> · required

Body

application/json

component_product_id · string<uuid> · required

quantity_per_kit · number · required

Required range: x >= 0

sort_order · integer · default: 0

Display order of the component within the kit.

notes · string | null

external_source · string | null

Source-system tag for historical migration (e.g. 'bubble_io', 'versa_cloud').

external_id · string | null

Source-system row id, persisted for batch traceability.

migration_batch_id · string<uuid> | null

Optional migration-wave identifier, persisted on the row.

imported_at · string<date-time> | null

Source record timestamp; preserve the origin system's created_at for audit fidelity.

Response

201

application/json

Component added

The response is of type object.