Skip to main content
POST
Add Kit Item Component

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

FlowAuthorization Code
Authorization URL
https://id.jtl-cloud.com/oauth/v2/authorize
Token URL
https://id.jtl-cloud.com/oauth/v2/token
Scopes1
items.write
Grants permission to create and modify item data.

Headers

x-companyid
string

The Company-Id (int or uuid) of the company on whose behalf the request is executed.

Idempotency-Key
string

Optional, client-generated key for deduplicating repeated write requests. A repeated request with the same key returns the originally recorded result instead of executing the effect again.

Required string length: 1 - 255
x-tenant-id
string<uuid>
required

The tenant ID for the target ERP instance.

Path Parameters

itemId
string<uuid>
required
Example:

"b45f6432-2462-4c6f-b00f-1d9d01000000"

Body

application/json

Request parameters

Adds a single component to an item's kit. Fine-grained alternative to replacing the whole component list, for targeted single-component changes without resending the list. The item has to be a kit already; converting a standard item into a kit is a separate endpoint still to be added (WAWI-91105). - Request

componentItemId
string<uuid>
required

Unique ID of the item to add as a component. The item must be eligible to become a kit component - an inactive item, an item that is itself a kit, a configuration item, a variation-combination parent and a partial-quantity item are all rejected - and it must not be the kit item itself.

Example:

"b45f6432-2462-4c6f-b00f-1d9d01000000"

quantity
number<decimal>
required

How many units of the component item one unit of the kit consumes. Must be greater than zero. A component item that is not divisible additionally rejects a fractional quantity.

comment
string

Free-text comment on the component. At most 255 characters. Omitting the field and sending an explicit null are equivalent - both store and return an empty string, never null.

position
integer<int32>

Zero-based position of the component within the kit's component list. Applied after the component has been added; defaults to the end of the list. A value outside the list bounds is clamped to the nearest end rather than rejected - this is intentional and mirrors the domain, where the desktop client moves a component with the same clamping logic. Read the Position of the response to learn where it ended up.

Response

Component was created in the item's kit. No Location header is returned: this API emits none on any operation, and the component is addressable without one via its ComponentItemId. The body is still worth reading for Position, which is the effective index after clamping.

Adds a single component to an item's kit. Fine-grained alternative to replacing the whole component list, for targeted single-component changes without resending the list. The item has to be a kit already; converting a standard item into a kit is a separate endpoint still to be added (WAWI-91105). - Response

componentItemId
string<uuid>
required

ID of the item that was added as a component. A kit component has no own single-value identifier - its identity is the pair of kit and component item - so this doubles as the component's identifier.

Example:

"b45f6432-2462-4c6f-b00f-1d9d01000000"

quantity
number<decimal>
required

How many units of the component item one unit of the kit consumes.

comment
string
required

The comment stored on the component. Always a string, never null - an omitted or explicitly null comment in the request is stored and returned as an empty string.

position
integer<int32>
required

The effective zero-based position of the component. This is the index the component actually ended up at, which differs from the requested one when the request was out of bounds and got clamped.