Order delegation

Overview

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

Delegation Lifecycle - Customer view

1. Order Confirmation & Stock Reservation

The process begins immediately after payment validation.

• Stock Blocking: The "Quantity Blocker" reserves inventory based on specific merchant and warehouse configurations.
• State Change: The order state in SCAYLE transitions to Confirmed.

2. Delegation Request & Transformation

Once confirmed, SCAYLE prepares the order for external fulfillment:

• Grouping: Order items are grouped by their respective merchant_ID.
• Transformation: The standard order payload is mapped into a merchant-specific JSON format.
• Forwarding: The request is sent via a Blocking Webhook. Unlike standard webhooks, the system halts further processing while awaiting a response.

3. Delegation Outcomes

SCAYLE reacts differently based on the merchant’s response:

4. Retry Policy & Failure Handling

If delegation fails due to merchant rejection or server errors, SCAYLE enters an automated recovery lifecycle:

• Initial Retries:
  • 1st Retry: 3 minutes after the initial failure.
  • 2nd Retry: 5 minutes after the first retry.
• Long-term Backoff:
  • The system retries every 2 hours for a total of 23 iterations.
• Total Duration: The retry window covers 44 hours and 8 minutes.

Final State: If all retries are exhausted, the order transitions from Aborted to Cancelled, and an order-cancelled webhook is dispatched.

5. Acknowledgement & Post-Processing

Merchants must acknowledge receipt of the delegation. This can happen in three ways:

1. Immediate (Synchronous): The merchant acknowledges via the direct response to the blocking webhook.
2. Deferred (Asynchronous): The merchant acknowledges later via a dedicated webhook.
3. Automatic: If no response is received within the timeout window, SCAYLE auto-acknowledges the request to prevent process stagnation.

[IMPORTANT]

Unshippable Items: If an item is not acknowledged or cannot be fulfilled, it is processed via a "Cancellation Shipment." This transitions the item to a cancelled state and triggers the item-unshippable webhook.

Delegation Lifecycle - Admin View

1. Merchant Configuration

To enable proper delegation:

• A Merchant must exist in SCAYLE and be configured with:
  • order_webhook_url
  • E.g., With basic Authentication
    • https://***:***@{tenant}.middleware.aboutyou.cloud/api/public/orders
  • E.g., Without basic authentication -
    • public URL - https://<hostname>/sha-ig-prd-orsv-we/v1/delegate-order`
• Supported transport types:
  • Webhook (CoreApiBlockingOrderWebhookTransform)
• Each merchant is linked to a warehouse and product variants.

2. Delegation Process

Order Delegation URL, which is specified during the merchant creation is utilized for delegating orders. Once orders are confirmed, 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.

json

Copy

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

json

Copy

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.