> ## Documentation Index
> Fetch the complete documentation index at: https://developer.jtl-software.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Update Kit Item Component
> Changes a single existing component of an item's kit in place. Fine-grained alternative to replacing the whole component list. Every field is optional - an omitted field keeps its current value, and a request that supplies no field at all succeeds with 200 without changing anything, unless the kit is controlled by a fulfillment network partner, which refuses every request with 409. Which item a component refers to cannot be changed; remove the component and add the other item instead.
## OpenAPI
````yaml /openapi/erp/2.2.json patch /v2/items/{itemId}/kit-items/components/{componentItemId}
openapi: 3.0.0
info:
title: JTL-WAWI API (Cloud)
description: "JTL-Wawi-Version: 2.3.0-alpha.261106180501+Sha.ea1f852\r\n# Introduction\r\n\r\nWelcome to the JTL-WAWI technical API documentation. This guide is here to help developers understand how our REST API works and how it can be integrated into your existing systems. We'll delve into the details of authentication and data manipulation processes, providing clear examples along the way. Whether you're a developer or an IT professional, this documentation aims to give you a practical understanding, laying the groundwork for effectively using the JTL-WAWI API to enhance your processes.\r\n\r\n# Authentication\r\n\r\nYou register your application with the API by sending a POST request with the required information and corresponding keys. You can find the exact request details at https://developer.jtl-software.com/products/erp/swagger/appregistration. This information has to include the following:\r\n\r\n* AppId\r\n* DisplayName\r\n* Description\r\n* Version\r\n* ProviderName\r\n* ProviderWebsite\r\n* MandatoryApiScopes\r\n\r\nThis data is crucial for identifying and registering your application with the API. The API uses it to generate a temporary authentication ID that allows your application to access the necessary resources. After successful validation of this information, you will receive the API key required for future authentication and API requests.\r\n\r\nBefore you can begin the registration process, you must open JTL-Wawi (new interface) and start the registration process under 'Admin->App registration'. Only at this point are you authorised to send the first API call. This step in JTL-Wawi ensures that your application is properly registered and has permission to use the API.\r\n\r\nThe API will send you an authentication ID in the form of a token. Once you have received this token and successfully completed the registration in JTL-Wawi, you will send another request to the API by including this authentication ID in the URL path.\r\n\r\nAfter successful validation of this second request by the API and confirmation of the correct information, you will be provided with the actual API key. It is important to note that this API key will not be displayed again!\r\n\r\nThis API key will be used in the future to authenticate requests to the API. It is of utmost importance that you securely store the API key upon receipt, as it cannot be retrieved from any other location in the system."
contact:
name: JTL-Software-GmbH
url: https://developer.jtl-software.com/
email: partner@jtl-software.com
version: '2.2'
x-application-version: 2.3.0.0
servers:
- url: https://api.jtl-cloud.com/erp
description: Production Environment Cloud API Gateway
security: []
tags:
- name: WMS
description: >-
Query all pick
lists for a specific wms warehouse that are not completed.
- name: Wawi App
description: >-
Get a
specific customer
- name: Warehouses
description: >-
Queries all
storage locations for a given warehouse.
- name: Units
description: Development
- name: Transaction Status
description: >-
Queries all transaction statuses for a sales
order.
- name: Tax
description: >-
Returns the tax
rate for the given item.
- name: Inventory
description: >-
Queries
stocks for a specific item, warehouse or storage location.
- name: Sales Order
description: >-
Queries
all cancellation reasons for sales orders.
- name: Sales Invoice Correction
description: >-
Queries all cancellation reasons for sales
invoice corrections.
- name: Return
description: >-
Create a new
return with associated items and packages.
- name: Item
description: >-
Queries all
responsible persons.
- name: Refund
description: >-
Queries all
cancellation reasons for refunds.
- name: Property
description: >-
Queries all
properties of items.
- name: Printer
description: >-
Retrieves all
installed printers.
- name: Master Data
description: >-
Queries
all on hold reasons for sales orders.
- name: Manufacturer
description: Development
- name: Label
description: Development
- name: Sales Invoice
description: >-
Gets a
specific invoice.
- name: Info
description: >-
Returns the
status of the API.
- name: Features
description: >-
Returns the
available feature sets with release state and API version.
- name: Extensibility
description: >-
Returns
the installed extensions.
- name: Shipment
description: Development
- name: Delivery Note
description: >-
Queries
all delivery notes.
- name: Custom Field
description: Development
- name: Customer
description: >-
Deletes a
specific customer.
- name: Authentication
description: >-
DEPRECATED seit Wawi 2.2.0: No-Op. Seit
Wawi 2.1.0 registriert sich die Wawi selbst per JWT.
- name: Attribute
description: Development
- name: Sales Quotation
description: >-
Execute the printing of a sales quotation
- name: Production
- name: Resources
- name: Sales Orders
- name: Marketplace Order
- name: Marketplace Offer
- name: Marketplace Invoicing
- name: Company
- name: Sales Channel
- name: Payment
- name: Warehouse Assistant
- name: Worker
paths:
/v2/items/{itemId}/kit-items/components/{componentItemId}:
patch:
tags:
- Item
summary: Update Kit Item Component
description: >-
Changes a single existing component of an item's kit in place.
Fine-grained alternative to replacing the whole component list. Every
field is optional - an omitted field keeps its current value, and a
request that supplies no field at all succeeds with 200 without changing
anything, unless the kit is controlled by a fulfillment network partner,
which refuses every request with 409. Which item a component refers to
cannot be changed; remove the component and add the other item instead.
operationId: Itemdetails_UpdateKitItemComponent
parameters:
- name: itemId
in: path
required: true
description: Unique ID of the kit item whose component is changed.
schema:
$ref: '#/components/schemas/JTL.Data.Contracts.Keys.ArtikelKey'
- name: componentItemId
in: path
required: true
description: >-
Unique ID of the component item to change. A kit component has no
own single-value identifier - its identity is the pair of kit and
component item - so the component item ID identifies the component.
schema:
$ref: '#/components/schemas/JTL.Data.Contracts.Keys.ArtikelKey'
- name: Idempotency-Key
in: header
description: >-
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.
schema:
type: string
maxLength: 255
minLength: 1
- name: x-tenant-id
in: header
required: true
schema:
type: string
format: uuid
description: The tenant ID for the target ERP instance.
requestBody:
x-name: UpdateKitItemComponentRequest
description: ''
content:
application/json:
schema:
$ref: >-
#/components/schemas/JTL.Wawi.Item.PublicApi.Endpoints.V2.Itemdetails.UpdateKitItemComponentRequest
required: true
x-position: 1
responses:
'200':
description: >-
The component was changed. The body is the full resulting component,
including the fields the request left unchanged and the effective
position after clamping.
content:
application/json:
schema:
$ref: >-
#/components/schemas/JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.UpdateKitItemComponentCommandResponse
'400':
description: >-
The request is invalid. Each validation error names the property it
belongs to - Quantity when it is null or outside the accepted range
of at least 0.0000000000001 and less than 1000000000000, Position
when it is null, or Comment when it exceeds 255 characters (error
code ValidationError), or Quantity when it is fractional for a
component item that is not divisible
(KitItemComponentQuantityInvalid). A request body carrying an
unknown member is rejected with 400 as well; that error is reported
without a property name.
content:
application/json:
schema:
$ref: '#/components/schemas/FastEndpoints.ProblemDetails'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/FastEndpoints.ProblemDetails'
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/FastEndpoints.ProblemDetails'
'404':
description: >-
No item with the specified ID was found (error code ItemNotFound),
or the kit has no component for the specified component item ID
(error code EntityNotFound) - add it through "POST
/v2/items/{itemId}/kit-items/components" or "AddKitItemComponent"
instead.
content:
application/json:
schema:
$ref: '#/components/schemas/FastEndpoints.ProblemDetails'
'409':
description: >-
The component cannot be changed in the item's current state. Either
the item exists but is not a kit (error code ItemNotAKit), or the
kit is controlled by a fulfillment network partner and may not be
changed here (error code KitItemNotChangeable). The latter does not
depend on the request body: it also answers a request that supplies
no field, and it takes precedence over a fractional quantity for a
component item that is not divisible.
content:
application/json:
schema:
$ref: '#/components/schemas/FastEndpoints.ProblemDetails'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/FastEndpoints.ProblemDetails'
security:
- oauth2-authorization-code:
- items.write
- oauth2-client-credentials:
- items.write
components:
schemas:
JTL.Data.Contracts.Keys.ArtikelKey:
type: string
format: uuid
example: b45f6432-2462-4c6f-b00f-1d9d01000000
additionalProperties: false
JTL.Wawi.Item.PublicApi.Endpoints.V2.Itemdetails.UpdateKitItemComponentRequest:
type: object
description: >-
Request model for UpdateKitItemComponent command endpoint.
Route parameters bind from the route, query parameters from the query
string, everything else from the body.
additionalProperties: false
properties:
quantity:
type: number
description: >-
How many units of the component item one unit of the kit consumes.
When omitted the quantity stays unchanged. Must be at least
0.0000000000001 and less than 1000000000000; null is rejected,
because a component cannot exist without a quantity. A component
item that is not divisible additionally rejects a fractional
quantity.
format: decimal
comment:
type: string
description: >-
Free-text comment on the component. At most 255 characters. When
omitted the comment stays unchanged. Send an empty string to remove
the comment. An explicit null removes it as well, but the REST
schema does not mark this field as nullable, so clients generated
from it should send the empty string. A removed comment is stored
and returned as an empty string, never null.
position:
type: integer
description: >-
Zero-based position of the component within the kit's component
list. When omitted the position stays unchanged; null is rejected. A
value outside the list bounds is clamped to the nearest end rather
than rejected. Read the Position of the response to learn where it
ended up.
format: int32
JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.UpdateKitItemComponentCommandResponse:
type: object
description: >-
Changes a single existing component of an item's kit in place.
Fine-grained alternative to replacing the whole component list. Every
field is optional - an omitted field keeps its current value, and a
request that supplies no field at all succeeds with 200 without changing
anything, unless the kit is controlled by a fulfillment network partner,
which refuses every request with 409. Which item a component refers to
cannot be changed; remove the component and add the other item instead.
- Response
additionalProperties: false
required:
- componentItemId
- quantity
- position
properties:
componentItemId:
$ref: '#/components/schemas/JTL.Data.Contracts.Keys.ArtikelKey'
description: >-
ID of the component item. 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.
quantity:
type: number
description: How many units of the component item one unit of the kit consumes.
format: decimal
comment:
type: string
description: >-
The comment stored on the component. Always a string, never null - a
removed comment is returned as an empty string.
position:
type: integer
description: >-
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.
format: int32
FastEndpoints.ProblemDetails:
type: object
additionalProperties: false
properties:
type:
type: string
default: https://www.rfc-editor.org/rfc/rfc7231#section-6.5.1
title:
type: string
default: One or more validation errors occurred.
status:
type: integer
format: int32
default: 400
instance:
type: string
default: /api/route
traceId:
type: string
default: 0HMPNHL0JHL76:00000001
detail:
type: string
errors:
type: array
items:
$ref: '#/components/schemas/FastEndpoints.ProblemDetails_Error'
FastEndpoints.ProblemDetails_Error:
type: object
additionalProperties: false
properties:
name:
type: string
default: Error or field name
reason:
type: string
default: Error reason
code:
type: string
severity:
type: string
securitySchemes:
oauth2-authorization-code:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://id.jtl-cloud.com/oauth/v2/authorize
tokenUrl: https://id.jtl-cloud.com/oauth/v2/token
scopes:
inventories.write: Grants permission to modify stock levels.
inventory.print: Grants permission to print inventory count lists.
inventory.read: Grants permission to read stock levels.
inventory.write: Grants permission to modify stock levels.
picklists.print: Grants permission to print pick lists.
picklists.write: Grants permission to create and modify pick lists.
warehouse.read: Grants permission to read warehouse data.
warehouses.print: Grants permission to print storage location labels.
warehouses.write: Grants permission to write warehouse data.
items.print: Grants permission to print item labels.
items.read: Grants permission to read item data.
items.write: Grants permission to create and modify item data.
procurements.read: Read procurement
saleschannels.read: Grants permission to read sales channels.
saleschannels.write: Grants permission to create and modify sales channels.
all.read: Allows the application to read all data.
customers.read: Grants permission to read customer data.
customers.write: Grants permission to create and modify customer data.
customfields.read: Grants permission to read custom fields.
customfields.write: Grants permission to create and modify custom fields.
deliveries.read: Grants permission to read deliveries.
deliveries.write: Grants permission to create and modify deliveries.
deliverynotes.print: Grants permission to print and output delivery notes.
deliverynotes.read: Grants permission to read delivery notes.
deliverynotes.write: Grants permission to create and modify delivery notes.
extensibility.integration: >-
Grants permission to manage extensions and integrations of the
JTL-Wawi.
inventories.read: Grants permission to read stock levels.
invoices.read: Grants permission to read invoices.
invoices.write: Grants permission to create and modify invoices.
labels.read: Grants permission to read labels.
labels.write: Grants permission to create and modify labels.
masterdata.read: >-
Read master data such as shipping methods, payment methods, color
codes and tax classes.
orders.read: Grants permission to read orders.
picklists.read: Grants permission to read pick lists.
returns.read: Grants permission to read returns.
returns.write: Grants permission to create and modify returns.
salesinvoicecorrections.read: Grants permission to read invoice corrections.
salesinvoicecorrections.write: Grants permission to create and modify invoice corrections.
salesorders.print: Grants permission to print and output sales orders.
salesorders.read: Grants permission to read sales orders.
salesorders.write: Grants permission to create and modify sales orders.
system.config.read: Grants permission to read the system configuration.
system.config.write: Grants permission to modify the system configuration.
taxes.read: Grants permission to read tax data.
wawiapp.all: Grants access to Wawi app related operations.
returns.mail: Grants permission to send returns by e-mail.
returns.print: Grants permission to print returns.
deliverynotes.mail: Grants permission to send delivery notes by e-mail.
customers.print: Grants permission to print customer details.
currencies.read: Grants read access to currencies.
dunning.mail: Grants permission to send dunning notices by e-mail.
dunning.print: Grants permission to print dunning notices.
dunning.read: >-
Grants read access to dunning: dunning levels, dunning notices,
dunning proposals, dunning runs and the dunning status of invoices
and customers.
dunning.write: >-
Grants write access to dunning: maintain dunning levels, issue and
withdraw dunning notices, start dunning runs and set dunning
blocks.
jera.read: Grants read access to JERA internal endpoints.
masterdata.write: Write master data
paymentmethods.read: Grants read access to payment methods.
payments.mail: Grants permission to send payment receipts by e-mail.
payments.read: Grants permission to read payments.
payments.write: Grants permission to write payments.
salescreditnotes.mail: Grants permission to send sales credit notes by e-mail.
salescreditnotes.print: Grants permission to print sales credit notes.
salescreditnotes.write: Grants permission to cancel credit notes.
salesinvoicecorrections.mail: Grants permission to send sales invoice corrections by e-mail.
salesinvoicecorrections.print: Grants permission to print and output invoice corrections.
salesinvoices.mail: Grants permission to send sales invoices by e-mail.
salesinvoices.print: Grants permission to print and output sales invoices.
salesinvoices.read: Grants read access to sales invoices.
salesinvoices.write: Grants write access to sales invoices.
salesorders.mail: Grants permission to send sales orders by e-mail.
salesquotations.mail: Grants permission to send sales quotations by e-mail.
salesquotations.print: Grants permission to print and output sales quotations.
salesquotations.read: Grants read access to sales quotations.
salesquotations.write: Grants write access to sales quotations.
salessubscriptions.read: Grants read access to subscriptions.
salessubscriptions.write: Grants write access to subscriptions.
system.worker.read: Read worker syncs
system.worker.write: Write worker syncs
worker.errors.read: Read the error log of the worker syncs
worker.read: Read the worker service and its syncs
worker.reset: Reset all worker syncs (destructive)
worker.write: Control and configure worker syncs
resources.read: Grants permission to read resource management data.
resources.write: Grants permission to create and modify resource management data.
pps.read: Grants permission to read production data.
pps.write: Grants permission to create and modify production data.
channels.read: Grants permission to read marketplace channels.
invoices.print: >-
Grants permission to print marketplace external documents
(invoices, credit notes).
marketplaceoffers.read: Grants permission to read marketplace offers and offer failures.
marketplaceoffers.write: Grants permission to create and modify marketplace offers.
notifications.read: Grants permission to read marketplace notifications.
orders.write: >-
Grants permission to modify marketplace order data (exclude/reset
cancellation, payment, return and shipping uploads).
scxoffers.read: >-
Grants permission to read SCX offer data, such as channel
attributes.
masterdata.company.irreversible.write: Perform irreversible company actions
masterdata.email.write: Write email configuration
taxes.write: Grants permission to create and modify tax data.
output.read: Grants permission to read output templates and document types.
output.write: Grants permission to manage output template sets.
users.read: Grants permission to read users, user groups and permissions.
users.write: >-
Grants permission to create and modify users, user groups and
their permissions.
incominginvoices.read: >-
Grants permission to read incoming invoices, including their line
items, additional costs and payments, and the additional cost
types.
incominginvoices.write: >-
Grants permission to create and modify incoming invoices,
including their line items, additional costs and payments, and to
maintain the additional cost types.
health.read: Read health
health.sessions.read: Read sessions and logged-in users
application.runas: >-
Allows the application to execute requests on behalf of another
user.
oauth2-client-credentials:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://id.jtl-cloud.com/oauth/v2/token
scopes:
inventories.write: Grants permission to modify stock levels.
inventory.print: Grants permission to print inventory count lists.
inventory.read: Grants permission to read stock levels.
inventory.write: Grants permission to modify stock levels.
picklists.print: Grants permission to print pick lists.
picklists.write: Grants permission to create and modify pick lists.
warehouse.read: Grants permission to read warehouse data.
warehouses.print: Grants permission to print storage location labels.
warehouses.write: Grants permission to write warehouse data.
items.print: Grants permission to print item labels.
items.read: Grants permission to read item data.
items.write: Grants permission to create and modify item data.
procurements.read: Read procurement
saleschannels.read: Grants permission to read sales channels.
saleschannels.write: Grants permission to create and modify sales channels.
all.read: Allows the application to read all data.
customers.read: Grants permission to read customer data.
customers.write: Grants permission to create and modify customer data.
customfields.read: Grants permission to read custom fields.
customfields.write: Grants permission to create and modify custom fields.
deliveries.read: Grants permission to read deliveries.
deliveries.write: Grants permission to create and modify deliveries.
deliverynotes.print: Grants permission to print and output delivery notes.
deliverynotes.read: Grants permission to read delivery notes.
deliverynotes.write: Grants permission to create and modify delivery notes.
extensibility.integration: >-
Grants permission to manage extensions and integrations of the
JTL-Wawi.
inventories.read: Grants permission to read stock levels.
invoices.read: Grants permission to read invoices.
invoices.write: Grants permission to create and modify invoices.
labels.read: Grants permission to read labels.
labels.write: Grants permission to create and modify labels.
masterdata.read: >-
Read master data such as shipping methods, payment methods, color
codes and tax classes.
orders.read: Grants permission to read orders.
picklists.read: Grants permission to read pick lists.
returns.read: Grants permission to read returns.
returns.write: Grants permission to create and modify returns.
salesinvoicecorrections.read: Grants permission to read invoice corrections.
salesinvoicecorrections.write: Grants permission to create and modify invoice corrections.
salesorders.print: Grants permission to print and output sales orders.
salesorders.read: Grants permission to read sales orders.
salesorders.write: Grants permission to create and modify sales orders.
system.config.read: Grants permission to read the system configuration.
system.config.write: Grants permission to modify the system configuration.
taxes.read: Grants permission to read tax data.
wawiapp.all: Grants access to Wawi app related operations.
returns.mail: Grants permission to send returns by e-mail.
returns.print: Grants permission to print returns.
deliverynotes.mail: Grants permission to send delivery notes by e-mail.
customers.print: Grants permission to print customer details.
currencies.read: Grants read access to currencies.
dunning.mail: Grants permission to send dunning notices by e-mail.
dunning.print: Grants permission to print dunning notices.
dunning.read: >-
Grants read access to dunning: dunning levels, dunning notices,
dunning proposals, dunning runs and the dunning status of invoices
and customers.
dunning.write: >-
Grants write access to dunning: maintain dunning levels, issue and
withdraw dunning notices, start dunning runs and set dunning
blocks.
jera.read: Grants read access to JERA internal endpoints.
masterdata.write: Write master data
paymentmethods.read: Grants read access to payment methods.
payments.mail: Grants permission to send payment receipts by e-mail.
payments.read: Grants permission to read payments.
payments.write: Grants permission to write payments.
salescreditnotes.mail: Grants permission to send sales credit notes by e-mail.
salescreditnotes.print: Grants permission to print sales credit notes.
salescreditnotes.write: Grants permission to cancel credit notes.
salesinvoicecorrections.mail: Grants permission to send sales invoice corrections by e-mail.
salesinvoicecorrections.print: Grants permission to print and output invoice corrections.
salesinvoices.mail: Grants permission to send sales invoices by e-mail.
salesinvoices.print: Grants permission to print and output sales invoices.
salesinvoices.read: Grants read access to sales invoices.
salesinvoices.write: Grants write access to sales invoices.
salesorders.mail: Grants permission to send sales orders by e-mail.
salesquotations.mail: Grants permission to send sales quotations by e-mail.
salesquotations.print: Grants permission to print and output sales quotations.
salesquotations.read: Grants read access to sales quotations.
salesquotations.write: Grants write access to sales quotations.
salessubscriptions.read: Grants read access to subscriptions.
salessubscriptions.write: Grants write access to subscriptions.
system.worker.read: Read worker syncs
system.worker.write: Write worker syncs
worker.errors.read: Read the error log of the worker syncs
worker.read: Read the worker service and its syncs
worker.reset: Reset all worker syncs (destructive)
worker.write: Control and configure worker syncs
resources.read: Grants permission to read resource management data.
resources.write: Grants permission to create and modify resource management data.
pps.read: Grants permission to read production data.
pps.write: Grants permission to create and modify production data.
channels.read: Grants permission to read marketplace channels.
invoices.print: >-
Grants permission to print marketplace external documents
(invoices, credit notes).
marketplaceoffers.read: Grants permission to read marketplace offers and offer failures.
marketplaceoffers.write: Grants permission to create and modify marketplace offers.
notifications.read: Grants permission to read marketplace notifications.
orders.write: >-
Grants permission to modify marketplace order data (exclude/reset
cancellation, payment, return and shipping uploads).
scxoffers.read: >-
Grants permission to read SCX offer data, such as channel
attributes.
masterdata.company.irreversible.write: Perform irreversible company actions
masterdata.email.write: Write email configuration
taxes.write: Grants permission to create and modify tax data.
output.read: Grants permission to read output templates and document types.
output.write: Grants permission to manage output template sets.
users.read: Grants permission to read users, user groups and permissions.
users.write: >-
Grants permission to create and modify users, user groups and
their permissions.
incominginvoices.read: >-
Grants permission to read incoming invoices, including their line
items, additional costs and payments, and the additional cost
types.
incominginvoices.write: >-
Grants permission to create and modify incoming invoices,
including their line items, additional costs and payments, and to
maintain the additional cost types.
health.read: Read health
health.sessions.read: Read sessions and logged-in users
application.runas: >-
Allows the application to execute requests on behalf of another
user.
````