JTL-Marketplaces (SCX)
/
Developer Guide
/
Orders
Last updated

Order Process

  • A new order must be created by calling POST /v1/channel/order first
  • 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 for a seller ID
  • It is not possible to add or change order lines once an order has been created.
  • Once an order is created, it can be updated using
    • PUT /v1/channel/order/status to update the status of an order or order item
    • PUT /v1/channel/order/address-update to update the address information

Order Status

  • CREATED: Orders with the status “created” are not yet ready for shipping. Orders with this status can be used for stock reservation. Once the order is ready for shipping, the status will change to ACCEPTED.
  • UNACKED: Orders with this status are not yet ready for shipping. The seller must first accept the order. Note: JTL-Wawi does not yet support order acknowledgment.
  • ACCEPTED: Orders with the status “accepted” are ready for shipping.

Order line item Status

Each order line item has a status, and this status should be used to determine the order status itself.

  • UNSHIPPED: The order line item is ready for shipping and can be shipped once the order is ACCEPTED.
  • SHIPPED: The order line item is marked as having been shipped.
  • CANCELED_BY_SELLER: The order line item has been cancelled by the seller.
  • CANCELED_BY_BUYER: The order line item has been cancelled by the buyer or the marketplace.
  • RETURNED: The order line item has been returned to the seller.
  • REFUNDED: The order line item has been refunded.

State transition - limits and rules

  • Orders with the statuses UNACKED or CREATED may not have valid address information.
  • An address update can only apply to orders with the statuses UNCACKED or CREATED.
  • Address information must be available before a status transition to ACCEPTED.
  • Once an order is assigned the status ACCEPTED, the order status cannot be changed.

The order item status can convey the following status information:

StautsUNSHIPPEDSHIPPEDCANCELED_BY_SELLERCANCELED_BY_BUYERRETURNEDREFUNDED
UNSHIPPED✓✓✓✓✓✓
SHIPPED-✓✓✓✓✓
CANCELED_BY_SELLER--✓---
CANCELED_BY_BUYER---✓--
RETURNED----✓✓
REFUNDED-----✓

Examples

Create a CREATED order using

// `POST 'https://scx-sbx.api.jtl-software.com/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 for an order with the status CREATED

// PUT 'https://scx-sbx.api.jtl-software.com/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 and set status to ACCEPTED

// PUT 'https://scx-sbx.api.jtl-software.com/v1/channel/order/status

{
	"orderList": [
		{
			"orderId": "OrderId_000001",
			"sellerId": "1",
			"orderStatus": "ACCEPTED"
		}
	]
}

Send a status change for an order line items

// PUT 'https://scx-sbx.api.jtl-software.com/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)

order_cancellation.png
  • Sellers send a cancellation request together with a CancellationRequestId which the client, i.e., JTL-Wawi, should remember in order to be able to assign the response later on.
  • The CancellationRequestId is used for the 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 included in the order must be specified. However, if only part of the order is cancelled, only the cancelled items must be specified.

Cancellation (by Buyer)

order_cancellation_buyer.png
  • Buyers or marketplaces send a cancellation request together with a CancellationRequestId.
  • The CancellationRequestId is used for the unique assignment of the data (OrderId / OrderItemIDs) to the channel.
  • A cancellation should always include all items to be cancelled. If the entire order is to be cancelled, all order items contained must also be specified. It is also possible to have partial order cancellations if only some individual items are cancelled.
  • Using this workflow on the channel side is considered optional- it is also possible to set the order status to “cancel”.

Return

return.png

Channel informs about upcoming return event

Note: This is an optional step in the workflow. 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.
    • The following data is provided:
      • OrderId
      • OrderItem List (ItemId, Quantity, Reason, Comment)
    • The following data can be provided optionally by the channel:
      • 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 now waits for the incoming return.

(Optional) Merchant decides that no return is required

Note: This is an optional step in the workflow.

The seller has the option to decide whether the customer needs to make a return. If no return is required, the POST /v1/seller/order/return can be sent by the seller after receiving the Channel:Order.Return event. The property requireReturnShipping should be set to false here.

Return shipment arrives at the seller’s warehouse

  • Once the return has arrived, the seller will check the items and confirm the return using POST /v1/seller/order/return.
  • If a return already exists in JTL -Wawi, the information stored there should be used to transfer the return to SCX.
    • This information includes the channelReturnId.
  • Furthermore, the following information about the individual order items must be transferred:
    • The order number (orderId)
    • The quantity that was returned
    • If the return is accepted (acceptReturn)
    • A condition must be specified
    • A reason can be specified
    • An additional note that can be stored

Refund

refund.png

Refunds are initiated directly by the seller, e.g. 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 after a success or failure back to the seller to ensure that a refund has been properly processed.

Previous page
Next page