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.

What you’ll learn:

How to create and update orders via the Channel API
Order and line-item status transitions
Cancellation workflows for both sellers and buyers
Return and refund processing

Order Lifecycle

High-level order lifecycle in SCX

Order Process

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.

The purchase date of an order must be after the creation date of the seller ID.
The orderId is unique and can only exist once per seller ID.
It is not possible to add or change order line items once an order has been created.

Order Status

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

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.

Examples

Create a CREATED Order

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

// PUT /v1/channel/order/status
{
  "orderList": [
    {
      "orderId": "OrderId_000001",
      "sellerId": "1",
      "orderStatus": "ACCEPTED"
    }
  ]
}

Update Order Line Item Status

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

By Seller
By Buyer

Cancellation by Seller

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.

Seller-initiated cancellation flow

Cancellation by Buyer

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

Return processing flow

Channel Informs About Upcoming Return

This is an optional step. Not all marketplaces support a return announcement.

Via the Channel:Order.Return event, the channel reports that a return process has been initiated on a connected marketplace:

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. Refund processing flow

Next Steps

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

Order Lifecycle

Order Process

Order Status

Order Line Item Status

State Transition Rules

Order Item Status Transition Matrix

Examples

Create a CREATED Order

Send Address Information

Update Order Status to ACCEPTED

Update Order Line Item Status

Cancellation

Cancellation by Seller

Cancellation by Buyer

Returns

Channel Informs About Upcoming Return

Merchant Decides No Return Is Required (Optional)

Return Shipment Arrives

Refunds

Next Steps

Product Sync

Seller Management

Rate Limits

Channel API Overview

Channel API Reference

Essentials

Cloud Apps

Marketplace Channels

ERP Integration

​Order Lifecycle

​Order Process

​Order Status

​Order Line Item Status

​State Transition Rules

​Order Item Status Transition Matrix

​Examples

​Create a CREATED Order

​Send Address Information

​Update Order Status to ACCEPTED

​Update Order Line Item Status

​Cancellation

​Cancellation by Seller

​Cancellation by Buyer

​Returns

​Channel Informs About Upcoming Return

​Merchant Decides No Return Is Required (Optional)

​Return Shipment Arrives

​Refunds

​Next Steps

Product Sync

Seller Management

Rate Limits

Channel API Overview

Channel API Reference

Order Lifecycle

Order Process

Order Status

Order Line Item Status

State Transition Rules

Order Item Status Transition Matrix

Examples

Create a CREATED Order

Send Address Information

Update Order Status to ACCEPTED

Update Order Line Item Status

Cancellation

Cancellation by Seller

Cancellation by Buyer

Returns

Channel Informs About Upcoming Return

Merchant Decides No Return Is Required (Optional)

Return Shipment Arrives

Refunds

Next Steps