> ## 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.
# Retrieves the full detail of a purchase order by its ID.
> Retrieves the full detail of a purchase order by its ID.
## OpenAPI
````yaml /openapi/erp/2.1.json get /v2/purchase-orders/{purchaseOrderId}
openapi: 3.0.0
info:
title: JTL-WAWI API (Cloud)
description: "JTL-Wawi-Version: 2.2.0-alpha.7921+Sha.4beffc3\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 Seller
- name: Seller
- name: Marketplace Order
- name: Marketplace Offer
- name: Marketplace Invoicing
- name: Sales Channel
- name: Payment
- name: Warehouse Assistant
- name: Worker
paths:
/v2/purchase-orders/{purchaseOrderId}:
get:
tags:
- wawi
- Purchase Order
summary: Retrieves the full detail of a purchase order by its ID.
description: Retrieves the full detail of a purchase order by its ID.
operationId: PurchaseOrderDomain_GetPurchaseOrderById
parameters:
- name: purchaseOrderId
in: path
required: true
description: The purchase order's ID.
schema:
$ref: >-
#/components/schemas/JTL.Data.Contracts.Keys.LieferantenBestellungKey
- name: x-tenant-id
in: header
required: true
schema:
type: string
format: uuid
description: The tenant ID for the target ERP instance.
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: >-
#/components/schemas/JTL.Wawi.PurchaseOrders.PublicApi.DataTransferObjects.V2.PurchaseOrderDomain.PurchaseOrder
'400':
description: Bad request.
content:
application/json: {}
'401':
description: Unauthorized.
content:
application/json: {}
'403':
description: Forbidden.
content:
application/json: {}
'404':
description: Not found.
content:
application/json: {}
'500':
description: Internal server error.
content:
application/json: {}
security:
- oauth2-authorization-code:
- purchaseorders.read
- oauth2-client-credentials:
- purchaseorders.read
components:
schemas:
JTL.Data.Contracts.Keys.LieferantenBestellungKey:
type: string
description: Der LieferantenBestellung Schlüssel.
format: uuid
example: b45f6432-2462-4c6f-b00f-1d9d01000000
additionalProperties: false
JTL.Wawi.PurchaseOrders.PublicApi.DataTransferObjects.V2.PurchaseOrderDomain.PurchaseOrder:
type: object
description: >-
The full detail of a purchase order, including its line items, addresses
and the supplier snapshot.
additionalProperties: false
required:
- purchaseOrderId
- supplierId
- status
- currencyIso
- currencyFactor
- isConfirmed
- lineItems
properties:
purchaseOrderId:
$ref: >-
#/components/schemas/JTL.Data.Contracts.Keys.LieferantenBestellungKey
description: Unique ID of the purchase order.
supplierId:
$ref: '#/components/schemas/JTL.Data.Contracts.Keys.LieferantKey'
description: ID of the supplier the order was placed with.
supplierName:
type: string
description: >-
The supplier's current display name, resolved at read time. NULL if
the supplier could not be resolved.
orderNumber:
type: string
description: The order's own number.
externalOrderNumber:
type: string
description: The buyer's own order number.
referenceOrderNumber:
type: string
description: A reference order number.
status:
$ref: >-
#/components/schemas/JTL.Wawi.PurchaseOrders.PublicApi.DataTransferObjects.V2.PurchaseOrderDomain.PurchaseOrderStatus
description: The order's current status.
currencyIso:
type: string
description: ISO code of the order's currency.
currencyFactor:
type: number
description: Conversion factor of the order's currency.
format: decimal
requestedDeliveryDate:
type: string
description: The delivery date requested from the supplier.
format: date-time
createdAt:
type: string
description: Date the order was created.
format: date-time
isConfirmed:
type: boolean
description: Whether the order has been confirmed by the supplier.
warehouseId:
$ref: '#/components/schemas/JTL.Data.Contracts.Keys.WarenlagerKey'
description: Target warehouse of the incoming goods.
companyId:
$ref: '#/components/schemas/JTL.Data.Contracts.Keys.FirmaKey'
description: The company the order was placed for.
internalComment:
type: string
description: Internal comment on the order, not communicated to the supplier.
lineItems:
type: array
description: The order's line items.
items:
$ref: >-
#/components/schemas/JTL.Wawi.PurchaseOrders.PublicApi.DataTransferObjects.V2.PurchaseOrderDomain.PurchaseOrderLineItem
deliveryAddress:
$ref: >-
#/components/schemas/JTL.Wawi.PurchaseOrders.PublicApi.DataTransferObjects.V2.PurchaseOrderDomain.PurchaseOrderAddress
description: Delivery address of the order.
billingAddress:
$ref: >-
#/components/schemas/JTL.Wawi.PurchaseOrders.PublicApi.DataTransferObjects.V2.PurchaseOrderDomain.PurchaseOrderAddress
description: Billing address of the order.
supplier:
$ref: >-
#/components/schemas/JTL.Wawi.PurchaseOrders.PublicApi.DataTransferObjects.V2.PurchaseOrderDomain.PurchaseOrderSupplierSnapshot
description: >-
Snapshot of the supplier's master data at the time the order was
created.
JTL.Data.Contracts.Keys.LieferantKey:
type: string
format: uuid
example: b45f6432-2462-4c6f-b00f-1d9d01000000
additionalProperties: false
JTL.Wawi.PurchaseOrders.PublicApi.DataTransferObjects.V2.PurchaseOrderDomain.PurchaseOrderStatus:
type: integer
description: >-
0 = Open, 5 = Released, 20 = InProgress, 30 = PartiallyDelivered, 50 =
Overdue, 500 = Completed
format: int32
x-enumNames:
- Open
- Released
- InProgress
- PartiallyDelivered
- Overdue
- Completed
enum:
- 0
- 5
- 20
- 30
- 50
- 500
JTL.Data.Contracts.Keys.WarenlagerKey:
type: string
format: uuid
example: b45f6432-2462-4c6f-b00f-1d9d01000000
additionalProperties: false
JTL.Data.Contracts.Keys.FirmaKey:
type: string
description: Represents a key for identifying a firm within the application.
format: uuid
example: b45f6432-2462-4c6f-b00f-1d9d01000000
additionalProperties: false
JTL.Wawi.PurchaseOrders.PublicApi.DataTransferObjects.V2.PurchaseOrderDomain.PurchaseOrderLineItem:
type: object
description: A single position of a purchase order.
additionalProperties: false
required:
- lineItemId
- lineItemType
- quantity
- deliveredQuantity
- openQuantity
- netPurchasePriceAmount
- vatRatePercentage
- sortOrder
properties:
lineItemId:
$ref: >-
#/components/schemas/JTL.Data.Contracts.Keys.LieferantenBestellungPosKey
description: Unique ID of the line item.
lineItemType:
$ref: >-
#/components/schemas/JTL.Wawi.PurchaseOrders.PublicApi.DataTransferObjects.V2.PurchaseOrderDomain.PurchaseOrderLineItemType
description: >-
The kind of position (item, free position, shipping position,
shipping surcharge, discount, small-quantity surcharge). Read-only
discriminator; the create path only ever produces item positions. A
NULL nPosTyp on the underlying row is coalesced to FreePosition — on
this column NULL and 0 are the same fact, not "unknown" (human
decision, resolves the legacy contradiction between accessors that
documented it as either).
itemId:
$ref: '#/components/schemas/JTL.Data.Contracts.Keys.ArtikelKey'
description: >-
ID of the ordered item, or NULL for a line item that never
references one (shipping position, surcharge, discount, free
position). The underlying kArtikel column is NOT NULL with no
CHECK/foreign key; a non-item position is written with the literal
0, which is coalesced to NULL here (human decision, live GraphQL bug
fix — exposing the raw 0 as an ID crashed the key-to-ID converter).
itemNumber:
type: string
description: The item's own article number.
supplierItemNumber:
type: string
description: The supplier's article number for this item.
name:
type: string
description: Name of the item.
supplierItemName:
type: string
description: The supplier's own name/description for this item.
quantity:
type: number
description: Ordered quantity.
format: decimal
deliveredQuantity:
type: number
description: Quantity delivered so far.
format: decimal
openQuantity:
type: number
description: Quantity not yet delivered.
format: decimal
netPurchasePriceAmount:
type: number
description: Net purchase price per unit.
format: decimal
vatRatePercentage:
type: number
description: VAT rate in percent.
format: decimal
deliveryTimeInDays:
type: integer
description: Delivery time in days.
format: int32
deliveryDate:
type: string
description: Requested delivery date for this position.
format: date-time
note:
type: string
description: Free-text note on the position.
sortOrder:
type: integer
description: Position's sort order within the order.
format: int32
packagingUnit:
type: string
description: Packaging unit designation.
packagingQuantity:
type: number
description: Quantity per packaging unit.
format: decimal
confirmedQuantity:
type: number
description: >-
Quantity confirmed by the supplier for this line item. NULL when no
confirmation has been received yet. Read-only — never settable
through this API.
format: decimal
confirmedDeliveryDate:
type: string
description: >-
Delivery date confirmed by the supplier for this line item. NULL
when no confirmation has been received yet. Read-only — never
settable through this API.
format: date-time
confirmedPrice:
type: number
description: >-
Net price confirmed by the supplier for this line item. NULL when no
confirmation has been received yet. Read-only — never settable
through this API.
format: decimal
isLineItemConfirmed:
type: boolean
description: >-
Whether the supplier has confirmed this line item. NULL when no
confirmation status has been set, distinct from false ("reviewed and
not confirmed"). Read-only — never settable through this API. Not to
be confused with the order header's IsConfirmed.
JTL.Wawi.PurchaseOrders.PublicApi.DataTransferObjects.V2.PurchaseOrderDomain.PurchaseOrderAddress:
type: object
description: >-
A postal address on a purchase order — delivery address or billing
address. Shared between the read side and the create command (the same
C# type backs both).
additionalProperties: false
properties:
salutation:
type: string
description: Form of address (e.g. Mr., Mrs.).
title:
type: string
description: Academic or professional title.
firstName:
type: string
description: First name of the contact.
lastName:
type: string
description: Last name of the contact.
companyName:
type: string
description: Company name.
additionalCompanyLine:
type: string
description: Additional company name line.
street:
type: string
description: Street and house number.
additionalAddressLine:
type: string
description: Additional address information.
postalCode:
type: string
description: Postal code.
city:
type: string
description: City.
state:
type: string
description: State or province.
countryIso:
type: string
description: >-
ISO code of the country (2 letters). When defaulted from a
warehouse, this may be empty — the source column is a free-text
country name that could not be resolved to an ISO code.
phoneNumber:
type: string
description: Phone number.
faxNumber:
type: string
description: Fax number.
mobilePhoneNumber:
type: string
description: Mobile phone number.
emailAddress:
type: string
description: Email address.
JTL.Wawi.PurchaseOrders.PublicApi.DataTransferObjects.V2.PurchaseOrderDomain.PurchaseOrderSupplierSnapshot:
type: object
description: >-
A snapshot of the supplier's master data as it was at the time the order
was created (the supplier's own data may change afterward; this snapshot
does not).
additionalProperties: false
properties:
companyName:
type: string
description: Supplier company name at the time of order.
additionalCompanyLine:
type: string
description: Additional company name line.
street:
type: string
description: Street and house number.
additionalAddressLine:
type: string
description: Additional address information.
postalCode:
type: string
description: Postal code.
city:
type: string
description: City.
state:
type: string
description: State or province.
countryIso:
type: string
description: ISO code of the country (2 letters).
phoneNumber:
type: string
description: Phone number.
faxNumber:
type: string
description: Fax number.
mobilePhoneNumber:
type: string
description: Mobile phone number.
emailAddress:
type: string
description: Email address.
contactSalutation:
type: string
description: Form of address of the supplier's contact person.
contactFirstName:
type: string
description: First name of the supplier's contact person.
contactLastName:
type: string
description: Last name of the supplier's contact person.
JTL.Data.Contracts.Keys.LieferantenBestellungPosKey:
type: string
description: Der LieferantenBestellungPos Schlüssel.
format: uuid
example: b45f6432-2462-4c6f-b00f-1d9d01000000
additionalProperties: false
JTL.Wawi.PurchaseOrders.PublicApi.DataTransferObjects.V2.PurchaseOrderDomain.PurchaseOrderLineItemType:
type: integer
description: >-
0 = FreePosition, 1 = Item, 2 = ShippingPosition, 6 = ShippingSurcharge,
10 = Discount, 11 = SmallQuantitySurcharge
format: int32
x-enumNames:
- FreePosition
- Item
- ShippingPosition
- ShippingSurcharge
- Discount
- SmallQuantitySurcharge
enum:
- 0
- 1
- 2
- 6
- 10
- 11
JTL.Data.Contracts.Keys.ArtikelKey:
type: string
format: uuid
example: b45f6432-2462-4c6f-b00f-1d9d01000000
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).
sellers.read: >-
Grants permission to read marketplace sellers and their
configuration.
sellers.write: >-
Grants permission to create and modify marketplace sellers and
their configuration.
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).
sellers.read: >-
Grants permission to read marketplace sellers and their
configuration.
sellers.write: >-
Grants permission to create and modify marketplace sellers and
their configuration.
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.
````