> ## 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.
# Updates the stock management configuration of an existing stock item.
> Updates the stock management configuration of an existing stock item. Every field is optional - omitted fields keep their current value, and a request that supplies no setting at all succeeds with 200 without changing anything. The item must already be a stock item; use POST /v2/items/{itemId}/stock-items/convert to turn a standard item into one first.
## OpenAPI
````yaml /openapi/erp/2.1.json patch /v2/items/{itemId}/stock-management
openapi: 3.0.0
info:
title: JTL-WAWI API (Cloud)
description: "JTL-Wawi-Version: 2.2.0-alpha.8513+Sha.92a26f6\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.1'
x-application-version: 2.2.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: Planned
- name: Sales Invoice Correction
description: Planned
- name: Return
description: >-
Create a new
return with associated items and packages.
- name: Item
description: >-
Queries all
responsible persons.
- name: Refund
description: Planned
- 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: Planned
- 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: Planned
- name: Shipment
description: Development
- name: Delivery Note
description: Planned
- 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: Company
- name: Sales Orders
- name: Marketplace Order
- name: Marketplace Offer
- name: Marketplace Invoicing
- name: Sales Channel
- name: Payment
- name: Warehouse Assistant
- name: Worker
paths:
/v2/items/{itemId}/stock-management:
patch:
tags:
- wawi
- Item
summary: Updates the stock management configuration of an existing stock item.
description: >-
Updates the stock management configuration of an existing stock item.
Every field is optional - omitted fields keep their current value, and a
request that supplies no setting at all succeeds with 200 without
changing anything. The item must already be a stock item; use POST
/v2/items/{itemId}/stock-items/convert to turn a standard item into one
first.
operationId: Itemdetails_ChangeStockItem
parameters:
- name: itemId
in: path
required: true
description: >-
Unique ID of the stock item whose stock management configuration is
updated.
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: ChangeStockItemRequest
description: ''
content:
application/json:
schema:
$ref: >-
#/components/schemas/JTL.Wawi.Item.PublicApi.Endpoints.V2.Itemdetails.ChangeStockItemRequest
required: true
x-position: 1
responses:
'200':
description: The stock management configuration was successfully updated.
content:
application/json:
schema:
$ref: >-
#/components/schemas/JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.ChangeStockItemCommandResponse
'400':
description: >-
The requested combination is not valid. Serial number tracking
cannot be combined with batch management, shelf life expiration
dates or divisible stock, and divisibilityType Subset cannot be set
through this endpoint.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/FastEndpoints.ProblemDetails'
'401':
description: Unauthorized.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/FastEndpoints.ProblemDetails'
'403':
description: Forbidden.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/FastEndpoints.ProblemDetails'
'404':
description: No item with the specified ID was found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/FastEndpoints.ProblemDetails'
'409':
description: >-
The item exists but the change does not fit its current state.
Either the item is not a stock item - use POST
/v2/items/{itemId}/stock-items/convert first - or one of these
conditions blocks the requested setting: switching
serialNumberTrackingType away from 'None' requires the item to have
no stock and no goods receipts; divisibilityType 'Divisible',
hasBatch and hasShelfLifeExpirationDate are each refused while
serial numbers are in use; hasBatch and hasShelfLifeExpirationDate
additionally require no stock and no goods receipts; or the item
type does not permit the setting at all, for example a
bill-of-materials item, a variation combination parent, a packaging
item or an item used in a fulfilment network. The response names the
condition that blocked it.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/FastEndpoints.ProblemDetails'
'500':
description: Internal server error.
content:
application/problem+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.ChangeStockItemRequest:
type: object
description: >-
Request model for ChangeStockItem command endpoint.
Route parameters bind from the route, query parameters from the query
string, everything else from the body.
additionalProperties: false
properties:
stockManagement:
$ref: >-
#/components/schemas/JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.UpdateItemStockManagement
description: >-
The stock management settings to change. Omitted settings keep their
current value.
JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.ChangeStockItemCommandResponse:
type: object
description: >-
Updates the stock management configuration of an existing stock item.
Every field is optional - omitted fields keep their current value, and a
request that supplies no setting at all succeeds with 200 without
changing anything. The item must already be a stock item; use POST
/v2/items/{itemId}/stock-items/convert to turn a standard item into one
first. - Response
additionalProperties: false
required:
- itemId
properties:
itemId:
$ref: '#/components/schemas/JTL.Data.Contracts.Keys.ArtikelKey'
description: Unique ID of the updated stock item.
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'
JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.UpdateItemStockManagement:
type: object
description: >-
Stock management configuration of an item. Determines whether and how
the item's stock is managed in warehouses - batch and shelf life
tracking, serial number capture, divisibility, buffers and negative
stock. This block configures stock *management*, not whether the item
has stock - an item without stock management can still carry stock, it
is simply not warehouse-managed. Actual stock levels are read via GET
/v2/items/{itemId}/stocks.
additionalProperties: false
properties:
hasShelfLifeExpirationDate:
type: boolean
description: >-
Indicates whether the item is managed with a shelf life expiration
date (SLED, German 'Mindesthaltbarkeitsdatum'). When enabled, every
stock posting for this item must carry an expiration date, so
perishable goods can be traced and picked by expiry. Mutually
exclusive with serial number tracking.
hasBatch:
type: boolean
description: >-
Indicates whether the item is managed in batches (German 'Charge').
When enabled, every stock posting for this item must carry a batch
number, so goods can be traced back to the batch they came from.
Mutually exclusive with serial number tracking, and freely
combinable with shelf life expiration dates.
serialNumberTrackingType:
$ref: >-
#/components/schemas/JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.SerialNumberTrackingType
type: integer
description: >-
Determines at which point in the goods flow serial numbers are
captured for this item. Any value other than 'None' is mutually
exclusive with batch management, shelf life expiration dates and
divisible stock.
format: int32
divisibilityType:
$ref: >-
#/components/schemas/JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.DivisibilityType
type: integer
description: >-
Determines whether the item's stock is held in whole units or in
fractional quantities. Any value other than 'None' is mutually
exclusive with serial number tracking.
format: int32
allowNegativeStock:
type: boolean
description: >-
Allows selling a higher quantity of the item than is physically in
stock. This global setting must be enabled before the
platform-specific or sales-channel-specific negative stock settings
below take any effect. Defaults to false when omitted.
buffer:
type: integer
description: >-
Safety stock buffer that is held back and not offered for sale. Used
when selling across sales channels that synchronise with a delay, so
that no more is sold than is actually available. Defaults to 0 when
omitted.
format: int32
globalMinimumStockLevel:
type: number
description: >-
Minimum stock level across all warehouses. When the total stock
falls below this value, the item is flagged for reordering and
appears in order suggestions and low-stock warnings. Defaults to 0
when omitted.
format: decimal
itemPlatformNegativeStocks:
type: array
description: >-
Platform-specific negative stock settings, for example for eBay or
Amazon. AllowNegativeStock must be enabled as well for any of these
to take effect.
items:
$ref: >-
#/components/schemas/JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.UpdateNegativeStockPlatform
itemSalesChannelNegativeStocks:
type: array
description: >-
Sales-channel-specific negative stock settings, allowing overselling
for individual shops or sales channels. AllowNegativeStock must be
enabled as well for any of these to take effect.
items:
$ref: >-
#/components/schemas/JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.UpdateNegativeStockSalesChannel
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
JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.SerialNumberTrackingType:
type: integer
description: 0 = None, 1 = OutboundOnly, 2 = InboundAndOutbound, 3 = EveryMovement
format: int32
x-enumNames:
- None
- OutboundOnly
- InboundAndOutbound
- EveryMovement
enum:
- 0
- 1
- 2
- 3
JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.DivisibilityType:
type: integer
description: 0 = None, 1 = Divisible, 2 = Subset
format: int32
x-enumNames:
- None
- Divisible
- Subset
enum:
- 0
- 1
- 2
JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.UpdateNegativeStockPlatform:
type: object
description: >-
Defines negative stock settings for a specific platform. This structure
enables individual configuration of negative stock handling per platform
(e.g., eBay, Amazon), allowing overselling for specific marketplaces
when the global AllowNegativeStock is enabled.
additionalProperties: false
required:
- platformId
- isNegativeStockAllowed
properties:
platformId:
$ref: '#/components/schemas/JTL.Data.Contracts.Keys.PlattformKey'
description: >-
Key of the platform that identifies the specific marketplace or
platform (e.g., eBay, Amazon) for which this negative stock setting
applies.
isNegativeStockAllowed:
type: boolean
description: >-
Determines if negative stock is allowed for this platform. When
true, orders can be accepted even when the item is out of stock on
this specific marketplace.
JTL.Wawi.Item.PublicApi.DataTransferObjects.V2.Itemdetails.UpdateNegativeStockSalesChannel:
type: object
description: >-
Defines negative stock settings for a specific sales channel. This
structure enables individual configuration of negative stock handling
per sales channel, allowing overselling for specific online shops when
the global AllowNegativeStock is enabled.
additionalProperties: false
required:
- salesChannelId
- isNegativeStockAllowed
properties:
salesChannelId:
$ref: '#/components/schemas/JTL.Wawi.Rest.Contracts.Models.SalesChannelId'
description: >-
Key of the sales channel that identifies the specific shop or sales
channel for which this negative stock setting applies.
isNegativeStockAllowed:
type: boolean
description: >-
Determines if negative stock is allowed for this sales channel. When
true, orders can be accepted even when the item is out of stock in
this specific channel.
JTL.Data.Contracts.Keys.PlattformKey:
type: string
format: uuid
example: b45f6432-2462-4c6f-b00f-1d9d01000000
additionalProperties: false
JTL.Wawi.Rest.Contracts.Models.SalesChannelId:
type: string
description: >-
Represents a unique identifier for a sales channel, encapsulating
various platform-specific keys such as shop,
user, or channel identifiers.
additionalProperties: false
securitySchemes:
oauth2-authorization-code:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://auth.jtl-cloud.com/oauth2/auth
tokenUrl: https://auth.jtl-cloud.com/oauth2/token
scopes:
inventories.write: Grants permission to modify stock levels.
inventory.read: Grants permission to read stock levels.
inventory.write: Grants permission to modify stock levels.
items.read: Grants permission to read item data.
items.write: Grants permission to create and modify item data.
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.
picklists.write: Grants permission to create and modify 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.
warehouse.read: Grants permission to read warehouse data.
wawiapp.all: Grants access to Wawi app related operations.
currencies.read: Grants read access to currencies.
jera.read: Grants read access to JERA internal endpoints.
paymentmethods.read: Grants read access to payment methods.
payments.read: Ermöglicht den Lesezugriff auf Zahlungen.
payments.write: Ermöglicht den Schreibzugriff auf Zahlungen.
salesinvoicecorrections.print: Grants permission to print and output invoice corrections.
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.
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.
system.worker.read: Worker-Synchronisationen lesen
system.worker.write: Worker-Synchronisationen schreiben
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).
masterdata.write: Write master data
taxes.write: Grants permission to create and modify tax data.
application.runas: >-
Allows the application to execute requests on behalf of another
user.
oauth2-client-credentials:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://auth.jtl-cloud.com/oauth2/token
scopes:
inventories.write: Grants permission to modify stock levels.
inventory.read: Grants permission to read stock levels.
inventory.write: Grants permission to modify stock levels.
items.read: Grants permission to read item data.
items.write: Grants permission to create and modify item data.
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.
picklists.write: Grants permission to create and modify 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.
warehouse.read: Grants permission to read warehouse data.
wawiapp.all: Grants access to Wawi app related operations.
currencies.read: Grants read access to currencies.
jera.read: Grants read access to JERA internal endpoints.
paymentmethods.read: Grants read access to payment methods.
payments.read: Ermöglicht den Lesezugriff auf Zahlungen.
payments.write: Ermöglicht den Schreibzugriff auf Zahlungen.
salesinvoicecorrections.print: Grants permission to print and output invoice corrections.
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.
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.
system.worker.read: Worker-Synchronisationen lesen
system.worker.write: Worker-Synchronisationen schreiben
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).
masterdata.write: Write master data
taxes.write: Grants permission to create and modify tax data.
application.runas: >-
Allows the application to execute requests on behalf of another
user.
````