Order Management

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.

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.

Create the order

A new order must be created by calling POST /v1/channel/order first.

Provide address information

If the order was created with status CREATED or UNACKED, send address data via PUT /v1/channel/order/address-update before transitioning to ACCEPTED.

Accept the order

Update the order status to ACCEPTED using PUT /v1/channel/order/status. The order is now ready for shipping.

Process line items

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

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 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.

// 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:

// 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.

// 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.

// 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.

By Seller
By Buyer

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.

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.

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.

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.

What’s Next?

Product Sync

Learn how listing and stock synchronization works.

Seller Management

Seller sign-up, update, and unlink flows.

Rate Limits

Per-endpoint quotas and 429 handling.

Channel API Overview

Events, metadata, and media content handling.

Channel API Reference

Full endpoint reference for the Channel API.

Essentials

Cloud Apps

Marketplace Channels

ERP Integration

Vouchers API

Order Lifecycle

Order Process

Order Constraints

Order Status

Order Line Item Status

State Transition Rules

Order Item Status Transition Matrix

Tax Handling

When `orderItem[].taxPercent` is provided

When `orderItem[].taxPercent` is omitted

Examples

Create a `CREATED` Order

Send Address Information

Update Order Status to `ACCEPTED`

Update Order Line Item Status

Cancellation

Returns

Channel Informs About Upcoming Return

Merchant Decides No Return Is Required (Optional)

Return Shipment Arrives

Refunds

What’s Next?

Product Sync

Seller Management

Rate Limits

Channel API Overview

Channel API Reference

​Order Lifecycle

​Order Process

​Order Constraints

​Order Status

​Order Line Item Status

​State Transition Rules

​Order Item Status Transition Matrix

​Tax Handling

​When orderItem[].taxPercent is provided

​When orderItem[].taxPercent is omitted

​Examples

​Create a CREATED Order

​Send Address Information

​Update Order Status to ACCEPTED

​Update Order Line Item Status

​Cancellation

​Returns

​Channel Informs About Upcoming Return

​Merchant Decides No Return Is Required (Optional)

​Return Shipment Arrives

​Refunds

​What’s Next?

Product Sync

Seller Management

Rate Limits

Channel API Overview

Channel API Reference

Order Lifecycle

Order Process

Order Constraints

Order Status

Order Line Item Status

State Transition Rules

Order Item Status Transition Matrix

Tax Handling

When `orderItem[].taxPercent` is provided

When `orderItem[].taxPercent` is omitted

Examples

Create a `CREATED` Order

Send Address Information

Update Order Status to `ACCEPTED`

Update Order Line Item Status

Cancellation

Returns

Channel Informs About Upcoming Return

Merchant Decides No Return Is Required (Optional)

Return Shipment Arrives

Refunds

What’s Next?