docs
  1. Products
  2. Manage Merchants
  3. Order Delegation

Order delegation

Overview

The Order Delegation process in SCAYLE orchestrates the handoff of confirmed customer orders from the SCAYLE Checkout system to merchants1 . This documentation outlines the end-to-end flow, technical touchpoints, payload structure, validation mechanisms, and recommendations for testing.

End-to-End Delegation Lifecycle

  1. Order Confirmation
    • Triggered once payment is validated.
    • Quantity blocker blocks stock using merchant and warehouse configuration.
    • Order transitions to the "Confirmed" state in SCAYLE.
  2. Delegation Request Creation and Trigger
    • Order Products are grouped by merchant ID.
    • An Order payload is transformed into merchant-specific request format (JSON).
    • Order is forwarded via blocking webhook.
  3. Delegation Outcomes
    • Complete Delegation: All items accepted → order-delegated webhook.
    • Partial Delegation: Some items accepted →
      • order-delegated + item-out-of-stock webhook.
    • Failed Delegation:
      • All merchants reject or fail (e.g. 500 errors) →
        • First retry after 3 minutes
        • Second retry after 5 minutes
        • Afterwards retrying every 2h, 23 times
        • Total retry time after confirmation: 46h 8m
        • The order status transitions from Aborted to Cancelled, triggering the order-cancelled webhook.
  4. Acknowledgement & Post-Processing
    • Acknowledgement may be:
      • Immediate (sync response)
      • Deferred via asynchronous webhook
      • Requests are auto acknowledged in case of no response.
    • Unshippable items are cancelled via cancellation shipment if not acknowledged which triggers item-unshippable webhook.

Technical Testing Process

Merchant Configuration

To enable proper delegation:

Delegation Process

Order Delegation URL which is specified during the update or create merchant will be utilized for delegating orders to merchants during order creation this ensures that order details are accurately passed on to the respective merchants, allowing them to process and fulfil the orders efficiently.

This webhook works in blocking mode, meaning requests are sent to them synchronously during the order creation.

Response

The order, including the items, is stored in SCAYLE before triggering the webhook. On receiving the order delegation request, if the endpoint responds with a status code other than 201 or an invalid response body, SCAYLE will automatically retry the request in increasing intervals for up to two days. Every retry will contain the same data. The webhook’s response must be idempotent, this means if the same order is being sent again, the webhook must respond with the same response (status code and quantities per order item).

For an order item to be deliverable, the response should contain a deliverableQuantity greater than 0. Order item is identified by items.*.id in the request and referenceKey in the response. If deliverableQuantity=0 is returned, SCAYLE will mark the item as unavailable.

Once responses from all merchants are collected, the customer will either:

  • Receive an indication in the confirmation email that the item is unavailable if other delegations succeeded, or
  • Receive a cancellation email if no delegations succeed.

Even if an item is undeliverable or cancelled, it will not be removed from the order and remains linked to it. If the order was paid in advance, customers will be refunded once the order is invoiced.

Status codeDescription
200The request was successfully processed
418Missing order items.
412Invalid price for order items (the total price for all order items = 0).
422Invalid order items data.
519Order already created
400Invalid parcel i.e item merchant is one of Baur or Otto and address_shipping.parcel_shop_id is set and not 0 .

Footnotes