How to integrate order delegation
Orders placed in SCAYLE’s Checkout are first delegated to SCAYLE’s Core system which holds a virtual stock for each item. SCAYLE cancels individual items (partial cancellation) or the full order (full cancellation) if certain items can not be fulfilled due to missing stock. As a consequence of this process, only fulfillable items are transferred as part of the webhook request.
This webhook request contains all required data, to fulfill the order. This includes ordered items with quantity, carrier and shipping data.
While there are also other webhooks that could be used for order delegation (e.g. order-comfirmed), using the blocking-order-creation webhook is the recommended approach in the SCAYLE ecosystem. The webhook is meant to be sent to a middleware that brokers the order to a fulfilment system. The full specification can be found in the here.
The Backbone Core API is different from the AdminAPI - therefore some keys and identifiers will have different names.
This tutorial describes the setup for the order delegation process using the blocking-order-creation webhook provided by SCAYLE. This webhook and the attached processes will use slightly different terminology, and this tutorial aims to enable partners to use this webhook to delegate orders to fulfillment systems.
Configuration
To set up the delegation process, the destination middleware needs to provide an endpoint that can handle the request and respond as defined in the section below. The endpoint should enforce Basic Auth with username and password.
To configure an order delegation endpoint with basic auth, use the following scheme: https://username:password@domain/path
When retrieving the configuration, username and password are masked.
There can be exactly 1 order_webhook_url per merchant, so if there is only one default merchant, only one order_webhook_url can be set.
Follow the instructions in the resource center for setting up order delegation here https://scayle.dev/en/developer-guide/products/manage-merchants/order-delegation . Set up the order delegation destination in SCAYLE can be done through the Admin API. Details about the request can be found here: https://scayle.dev/en/api-guides/admin-api/resources/merchants/update-a-merchant .
Request
Approximately one minute after order confirmation, SCAYLE sends the webhook with the following payload:
This web hook has a timeout of 15 seconds, which should be considered when designing processes around enriching the order data (e.g. with requests to the AdminAPI). The webhook is delivered at least once, and retried every two hours for up to 48 hours if your endpoint responds with an error or times out.\
Response
In a success case, SCAYLE expects a response with a HTTP status of 201 and the following payload in the response body:
Your endpoint must handle webhook requests idempotently, i.e. if the exact same order (even with a different X-Request-Id) is sent again, the endpoint must respond with the exact same response (status code and quantities per order item) and ensure that no duplicates are created.
The following mapping logic applies between the order delegation request from BCO and the response the middleware should send:
orderDelegationResult | fixed value | “acknowledged” |
|---|---|---|
referenceKey | referenceKey | |
merchantReferenceKey | fulfillingMerchantKey | |
items | iterate through all items | - |
items[].referenceKey | items[].referenceKey | |
items[].merchantReferenceKey | items[].merchantKey | |
items[].deliverableQuantity | fixed value | e.g 1 |
\
