> ## 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. # Order Management > Handle orders across marketplace channels: creation, status updates, cancellations, returns, and refunds. This guide covers the full order lifecycle in SCX: creating orders, managing status transitions, handling cancellations from both sides, processing returns, and issuing refunds. ## Order Lifecycle An order moves from creation through acceptance, shipping, and any post-order handling such as returns or refunds. ```mermaid theme={null} stateDiagram-v2 [*] --> CREATED: Channel creates order [*] --> UNACKED: Channel creates order (requires ack) UNACKED --> ACCEPTED: Seller acknowledges CREATED --> ACCEPTED: Address provided state ACCEPTED { [*] --> UNSHIPPED UNSHIPPED --> SHIPPED: Seller ships UNSHIPPED --> CANCELED_BY_SELLER: Seller cancels UNSHIPPED --> CANCELED_BY_BUYER: Buyer cancels SHIPPED --> RETURNED: Buyer returns SHIPPED --> CANCELED_BY_SELLER: Seller cancels SHIPPED --> CANCELED_BY_BUYER: Buyer cancels RETURNED --> REFUNDED: Seller refunds } ``` ## Order Process Orders are processed in four stages: create the order, provide address information (if required), accept the order, and update individual line items as fulfillment progresses. A new order must be created by calling `POST /v1/channel/order` first. If the order was created with status `CREATED` or `UNACKED`, send address data via `PUT /v1/channel/order/address-update` before transitioning to `ACCEPTED`. Update the order status to `ACCEPTED` using `PUT /v1/channel/order/status`. The order is now ready for shipping. Update individual order item statuses (shipped, cancelled, returned, refunded) via `PUT /v1/channel/order/status`. ### Order Constraints * An order's purchase date must be later than the seller's creation date. * An `orderId` must be be unique for each seller. * Order line items cannot be added, removed, or modified after the order has been created. ## Order Status An order carries one of the following statuses. | Status | Description | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `CREATED` | The order is not yet ready for shipping. Can be used for stock reservation. Once ready for shipping, the status changes to `ACCEPTED`. | | `UNACKED` | The order is not yet ready for shipping. The seller must first accept the order. **Note:** JTL-Wawi does not yet support order acknowledgment. | | `ACCEPTED` | The order is ready for shipping. | ## Order Line Item Status Each order line item has a status that should be used to determine the overall order status: | Status | Description | | -------------------- | ----------------------------------------------------------- | | `UNSHIPPED` | Ready for shipping; can be shipped once order is `ACCEPTED` | | `SHIPPED` | Marked as having been shipped | | `CANCELED_BY_SELLER` | Cancelled by the seller | | `CANCELED_BY_BUYER` | Cancelled by the buyer or the marketplace | | `RETURNED` | Returned to the seller | | `REFUNDED` | Refunded | ## State Transition Rules The following rules govern when an order can change status. * Orders with status `UNACKED` or `CREATED` may not have valid address information. * An address update can only apply to orders with status `UNACKED` or `CREATED`. * Address information must be available before a status transition to `ACCEPTED`. * Once an order is assigned status `ACCEPTED`, the order status cannot be changed. ### Order Item Status Transition Matrix The table below shows which transitions between order item statuses are allowed: | From / To | UNSHIPPED | SHIPPED | CANCELED\_BY\_SELLER | CANCELED\_BY\_BUYER | RETURNED | REFUNDED | | -------------------- | --------- | ------- | -------------------- | ------------------- | -------- | -------- | | UNSHIPPED | yes | yes | yes | yes | yes | yes | | SHIPPED | - | yes | yes | yes | yes | yes | | CANCELED\_BY\_SELLER | - | - | yes | - | - | - | | CANCELED\_BY\_BUYER | - | - | - | yes | - | - | | RETURNED | - | - | - | - | yes | yes | | REFUNDED | - | - | - | - | - | yes | ```mermaid theme={null} flowchart LR U[UNSHIPPED] --> S[SHIPPED] S --> RT[RETURNED] RT --> RF[REFUNDED] style U fill:#FFF2EB,stroke:#FB581F,color:#0B1B45 style S fill:#FFF2EB,stroke:#FB581F,color:#0B1B45 style RT fill:#E8F4FF,stroke:#89D2FF,color:#0B1B45 style RF fill:#EEEEE7,stroke:#0B1B45,color:#0B1B45 ``` This is the normal lifecycle. From `UNSHIPPED` or `SHIPPED`, an item can also jump directly to `CANCELED_BY_SELLER`, `CANCELED_BY_BUYER`, or `REFUNDED`; from `UNSHIPPED` it can additionally go straight to `RETURNED`. ## Tax Handling The `orderItem[].taxPercent` field controls how VAT is applied to each order line item in JTL-Wawi. The field is optional and accepts a stringified numeric value (e.g. `"20"`, `"7"`). See the [Channel API Reference](/api-reference/scx/channel) for the full order payload schema. ### When `orderItem[].taxPercent` is provided JTL-Wawi uses the value directly as the tax rate for that line item. This gives the channel full control over the applied VAT, for example setting `"20"` for a French buyer or `"21"` for a Spanish buyer. ### When `orderItem[].taxPercent` is omitted JTL-Wawi calculates the tax rate itself based on: * The **tax class** of the matched article in JTL-Wawi * The **tax zone configuration** of the seller's JTL-Wawi instance (shipping country, tax rules, etc.) The resulting tax rate depends entirely on the individual seller's JTL-Wawi setup. If the seller has configured tax zones correctly for international shipments (e.g. France 20%, Spain 21%), JTL-Wawi can apply the appropriate country-specific rate. Otherwise the seller's default domestic rate applies (e.g. 19% / 7% for Germany), depending on their configuration. For unmatched line items (i.e. the SKU does not match any article in JTL-Wawi), the ERP default tax rate applies. ## Examples The following examples walk through an order from creation to line-item status update. ### Create a `CREATED` Order This request creates an order with status `CREATED` and two line items plus shipping. ```json theme={null} // POST /v1/channel/order { "orderList": [ { "sellerId": "1", "orderStatus": "CREATED", "orderId": "OrderId_000001", "purchasedAt": "2020-02-25T15:05:20+00:00", "lastChangedAt": "2020-02-25T15:05:20+00:00", "currency": "EUR", "orderItem": [ { "orderItemId": "SHIPPING-0001", "type": "SHIPPING", "grossPrice": "2.00", "taxPercent": "19", "quantity": "1.0", "shippingGroup": "test" }, { "orderItemId": "ABC-0001", "type": "ITEM", "grossPrice": "19.99", "total": "19.99", "taxPercent": "19", "sku": "1234", "channelOfferId": "1", "quantity": "1", "title": "Eine Hose (4006680069951)", "note": "Zur Auswahl" }, { "orderItemId": "ABC-0002", "type": "ITEM", "grossPrice": "19.99", "total": "19.99", "taxPercent": "19", "sku": "ART-WAWI-55070", "channelOfferId": "2", "quantity": 1, "title": "Ein Hemd (ART-WAWI-55070)", "note": "Zur Auswahl" } ] } ] } ``` ### Send Address Information Send address information for an order with status `CREATED`: ```json theme={null} // PUT /v1/channel/order/address-update { "orderList": [ { "orderId": "OrderId_000001", "sellerId": "1", "billingAddress": { "firstName": "Arno", "lastName": "Nym", "gender": "male", "street": "Am Feld", "houseNumber": "16", "postcode": "123456", "city": "Dingenskirschen", "country": "DE" }, "shippingAddress": { "firstName": "Arno", "lastName": "Nym", "gender": "male", "street": "Am Feld", "houseNumber": "16", "postcode": "123456", "city": "Dingenskirschen", "country": "DE" } } ] } ``` ### Update Order Status to `ACCEPTED` This request transitions the order to `ACCEPTED`, making it ready for shipping. ```json theme={null} // PUT /v1/channel/order/status { "orderList": [ { "orderId": "OrderId_000001", "sellerId": "1", "orderStatus": "ACCEPTED" } ] } ``` ### Update Order Line Item Status This request marks individual line items as shipped and paid. ```json theme={null} // PUT /v1/channel/order/status { "orderList": [ { "orderId": "OrderId_000001", "sellerId": "1", "orderStatus": "ACCEPTED", "orderItems": [ { "orderItemId": "ABC-0001", "itemStatus": "SHIPPED", "paymentStatus": "PAID" }, { "orderItemId": "ABC-0002", "itemStatus": "SHIPPED", "paymentStatus": "PAID" } ] } ] } ``` ## Cancellation Cancellations can originate from the seller or from the buyer, and each path follows its own flow. Sellers send a cancellation request with a `CancellationRequestId` which JTL-Wawi uses to assign the response later. * The `CancellationRequestId` provides unique assignment of the data (OrderId / OrderItemIDs) to the client. * A cancellation should always include all items to be cancelled. If the entire order is cancelled, all order items must be specified. For partial cancellation, only the cancelled items need to be specified. ```mermaid theme={null} sequenceDiagram participant Seller as Seller (JTL-Wawi) participant SCX as SCX Platform participant Channel as Channel Integration Seller->>SCX: Seller:Order.CancellationRequest event SCX->>Channel: Event includes CancellationRequestId + items Channel->>Channel: Process cancellation on marketplace Channel->>SCX: Update order item status to CANCELED_BY_SELLER ``` Buyers or marketplaces send a cancellation request with a `CancellationRequestId`. * The `CancellationRequestId` provides unique assignment of the data (OrderId / OrderItemIDs) to the channel. * A cancellation should always include all items to be cancelled. Partial order cancellations are supported. Using the buyer cancellation workflow on the channel side is optional. You can simply set the order status to `CANCELED_BY_BUYER` instead. ```mermaid theme={null} sequenceDiagram participant Buyer participant Channel as Channel Integration participant SCX as SCX Platform participant Seller as Seller (JTL-Wawi) Buyer->>Channel: Requests cancellation Channel->>SCX: Channel:Order.CancellationRequest event SCX->>Seller: CancellationRequest with CancellationRequestId alt Seller accepts Seller->>SCX: CancellationAccepted event SCX->>Channel: Event delivered Channel->>Channel: Update items to CANCELED_BY_BUYER else Seller denies Seller->>SCX: CancellationDenied event SCX->>Channel: Event delivered end ``` **Buyer-initiated cancellation flow** ## Returns A return can be announced by the channel, processed with or without a return shipment, and confirmed back to the seller. ```mermaid theme={null} sequenceDiagram participant Buyer participant Channel as Channel Integration participant SCX as SCX Platform participant Seller as Seller (JTL-Wawi) Buyer->>Channel: Initiates return Channel->>SCX: Channel:Order.Return event SCX->>Seller: Return announcement alt No return shipping required Seller->>SCX: POST /v1/seller/order/return (requireReturnShipping=false) else Return shipping required Note over Seller: Wait for return shipment Buyer->>Seller: Ships items back Seller->>Seller: Inspect returned items Seller->>SCX: POST /v1/seller/order/return (with item details) end SCX->>Channel: Seller:Order.ReturnProcessingResult event ``` ### Channel Informs About Upcoming Return The `Channel:Order.Return` event notifies SCX that a return has been initiated on the connected marketplace. This event is optional. Not all marketplaces support return announcements. The event carries the following data: * **Required data:** OrderId, OrderItem List (ItemId, Quantity, Reason, Comment) * **Optional data:** ChannelReturnId (internal ID to identify the return case), Return Tracking Information (Carrier, TrackingNo.) JTL-Wawi stores the upcoming return case: * If no item return is required, the return can be answered directly via `POST /v1/seller/order/return`. * If a return is required, the seller waits for the incoming return. ### Merchant Decides No Return Is Required (Optional) The seller can decide whether the customer needs to make a return. If no return is required, `POST /v1/seller/order/return` can be sent after receiving the `Channel:Order.Return` event with the `requireReturnShipping` property set to `false`. ### Return Shipment Arrives Once the return has arrived, the seller checks the items and confirms the return using `POST /v1/seller/order/return`. If a return already exists in JTL-Wawi, the stored information (including the `channelReturnId`) should be used. The following information about individual order items must be transferred: | Field | Required | Description | | -------------- | -------- | ------------------------------ | | `orderId` | Yes | The order number | | `quantity` | Yes | The quantity that was returned | | `acceptReturn` | Yes | Whether the return is accepted | | `condition` | Yes | Condition of the returned item | | `reason` | No | Reason for the return | | `note` | No | Additional note | ## Refunds Refunds are initiated directly by the seller, for example after a return has been processed or following an agreement with the buyer (via ticket/email/phone). The channel processes the refund and sends a `Channel:Order.RefundProcessingResult` event back to the seller to confirm whether the refund was processed successfully or failed. ```mermaid theme={null} sequenceDiagram participant Seller as Seller (JTL-Wawi) participant SCX as SCX Platform participant Channel as Channel Integration Seller->>SCX: Seller:Order.Refund event SCX->>Channel: Refund request with item details Channel->>Channel: Process refund on marketplace alt Refund successful Channel->>SCX: Channel:Order.RefundProcessingResult (success) else Refund failed Channel->>SCX: Channel:Order.RefundProcessingResult (failed) end SCX->>Seller: RefundProcessingResult event ``` *** ## What's Next? Learn how listing and stock synchronization works. Seller sign-up, update, and unlink flows. Per-endpoint quotas and 429 handling. Events, metadata, and media content handling. Full endpoint reference for the Channel API.