General
SCAYLE allows you to retrieve order data with all related information such as address, customer, items and etc. You can also update the order reference key.
Orders have different statuses that depend on the shipping, billing, and item statuses. These statuses help you to track the order progress, inform customers, and troubleshoot.
Depending on the state in the order flow, the Admin API returns status information consisting of the following:
detailedStatus.order(e.g,order_created,order_pended,order_confirmed)detailedStatus.billing(e.g.,shipping_open,shipping_ordered)detailedStatus.shipping(e.g.,billing_open,billing_completed)items.statusfor each item in the order (e.g.,available,returned)
The shipping, billing, and item statuses determine the overall status.
Order Status
Overall Order Status
The following order statuses can be triggered during the checkout process. Each order status corresponds to a status in the SCAYLE Panel.
| Status | Description | SCAYLE Panel Label |
|---|---|---|
order_created, order_open | As soon as the customer enters the checkout (i.e., when an order is created). Or when an order is reverted back from order_pended. | Open |
order_pended | As soon as the customer places an order by clicking on the “Confirmed” button. This triggers the validation process with the chosen Payment Service Provider (PSP). It is possible that the order never leaves the state order_pended (e.g., customer logs out before completing the process). | Payment Pending |
order_confirmed | As soon as the Payment Service Provider validation is successful the state changes to order_confirmed. | Payment Reserved |
order_delegated | The status transitions to order_delegated when the order is delegated to the merchants associated with the order items. | Payment Reserved |
order_shipped | The status transitions to order_shipped when the shipping process started and the merchants send a shipping notification. | Shipped |
order_invoiced | As soon as the Invoice.pdf is created. This triggers the sending of the order confirmation email. This is an optional step if the invoicing is done by SCAYLE. If invoicing is done in an ERP the order state does not change. | Completed |
order_aborted | When an order cancellation is sent a record to cancel the order is created. While the record has status pending, the cancellation is pending. | Payment Cancelled |
order_cancelled | The order is fully cancelled. | Payment Cancelled |
order_imported | The order is imported. This status generally applies to orders migrated from previous systems. | - |
order_invoice_error | There was an error generating the invoice. | - |
Shipping Status
| Status | Description | SCAYLE Panel Label |
|---|---|---|
shipping_open | When a customer enters checkout, through payment reservation, until delegation. | New |
shipping_ordered | When the order is delegated to the merchants associated with the items of the order. | Ordered |
shipping_delivered | When the shipping process starts and the merchants send a shipping notification. | Shipped |
shipping_cancelled | The order is fully cancelled. | Cancelled |
shipping_undeliverable | Information from the merchant indicates the items are not deliverable. | Not deliverable |
shipping_partially_delivered | For orders with multiple items, information from the merchant indicates at least one item is not deliverable. | Partially undelivered |
Billing Status
| Status | Description | SCAYLE Panel Label |
|---|---|---|
billing_open | As soon as the customer enters the checkout (i.e., when an order is created). Or when an order is reverted back from payment_pending. | Open |
billing_pending | As soon as the customer places an order by clicking on the “Confirmed” button. | Open |
billing_payment_pending | When the customer confirms they want to order and they are redirected to the payment provider. | Payment Pending |
billing_completed | As soon as the Invoice.pdf is created. This triggers the sending of the order confirmation email. | Completed |
billing_payment_aborted | Customer aborts the payment process between billing_open and billing_payment_pending. | - |
billing_payment_cancelled | The order is cancelled due to no deliverable items or customer explicitly cancels the order. | Payment Cancelled |
billing_refunded | The order is refunded. | Refunded |
billing_denied | - | - |
Item Status
The following statuses are possible at the item-level. To understand how status changes at the item level affect the shipping and billing status, see the Order Flow table below.
| Status | Description | Corresponding Order State |
|---|---|---|
| available | Item is available. | Shipping |
| unavailable | Item is not available. | Shipping |
| deliverable | Information from the merchant indicates item is deliverable. | Delegated |
| undeliverable | Information from the merchant indicates item is not deliverable. | Delegated |
| cancelled | Item cancelled. | Shipping |
| returned | Item cancelled. | Invoiced |
Dependencies
The following table outlines which statuses can occur together.
| Order Status | Shipping Status | Billing Status | SCAYLE Panel Shipping Status | SCAYLE Panel Billing Status |
|---|---|---|---|---|
order_created | shipping_open | Open | New | Open |
order_pended | shipping_open | billing_pending | New | Payment Pending |
order_confirmed | shipping_open | billing_pending, billing_payment_pending, external_payment_pending or billing_completed | New | Payment Pending |
order_delegated | shipping_ordered | billing_pending, billing_payment_pending, external_payment_pending or billing_completed | New | Payment Pending |
order_shipped | shipping_delivered | billing_pending, billing_payment_pending, external_payment_pending or billing_completed | Shipped | Payment Pending |
order_invoiced | shipping_delivered | billing_payment_pending , external_payment_pending or billing_completed | Shipped | Payment Pending, Completed |
order_aborted | - | - | - | Payment Cancelled |
order_cancelled | shipping_cancelled, shipping_undeliverable or shipping_not_deliverable | billing_payment_aborted, billing_payment_cancelled, billing_refunded or billing_denied | Cancelled, Not Deliverable | Payment Cancelled, Refunded |
order_invoiced | shipping_partially_delivered | billing_payment_pending, external_payment_pending or billing_completed Partially Undelivered | Payment Pending, Completed |
Order flow
For each step in the order flow, an order has both a Shipping Status and a Billing Status as indicated in the diagram below. The table below describes each step, including how item-level changes affect the statuses.
Billing and Shipment statuses
| Step | Summary | Description |
|---|---|---|
| 1 | Customer enters checkout | As soon as the customer enters the checkout (i.e., Basket transferred from the Shop to the Checkout system), an order will be created (regardless of whether the customer is logged in or not). If the customer is logged in, the connection between the order and customer is already made. |
| 2 | Customer aborts checkout | If the customer interrupts the checkout process without finishing it (e.g., the customer closes the browser), the order and statuses will remain in the system. If the customer logs into their profile again, this order will not be displayed. Third-party systems will not know about these orders, because no notification/webhook will be sent. |
| 3 | Items not available (edge case) | In some cases, items get reserved during the process and are not available for the current basket (run out of a virtual stock). Since it is not possible to purchase them, the order will be empty and keep the statuses (similar to step 2). |
| 4 | Order confirmation | The customer confirms they want to order the items. They will be redirected to the payment provider (e.g. PayPal). Billing status changes to PAYMENT PENDING. Checkout waits for the response of the PSP to confirm payment coverage. If the payment is not covered/successful, the billing status switches back to NEW. |
| 5 | Customer aborts payment | If the customer aborts the payment process, the order will still be kept in the system (similar to step 2). In this case, the billing status is PAYMENT PENDING. |
| 6 | Payment is covered | The payment is covered. Depending on the PSP used, the responses may look different. For example, PayPal delivers all required data with the response and adds them to the return URL. Other services (e.g., Adyen) do not deliver the payment information right away and the status is updated to PAYMENT RESERVED after a webhook indicating the transaction was successful. Generally, the process is very fast, so the customer will not notice this response period. |
| 7 | Order delegation | After successful payment reservation, Checkout delegates the order to SCAYLE. Virtual stocks for items are verified. An artificial delay of one minute is added as a safety measure. The order confirmation webhook is triggered. After the delegation, a confirmation mail is sent to the customer. If SCAYLE has any problems processing the delegation, it will retry every minute for two days. If not successful after two days, the order is CANCELLED. If at least one item is valid, the shipping status is ORDERED. Billing status remains unchanged. |
| 8 | Items not available | If there is not at least one item of the order in stock/deliverable, the whole order gets CANCELLED. There is no further processing of the order. A mail will be sent informing the customer of cancellation. |
| 9 | Items available | If at least one item of the successful order is available, the shipment phase begins. If an item is deliverable, it will get the status SHIPPED and a shipment notification is sent. If it is not deliverable, the item gets cancelled. In this case, a notification is also sent. |
| 10 | Shipping cancelled | If all items of the order get the shipment status CANCELLED, the order gets is status too. A notification mail is sent. |
| 11 | Shipped | After the status of the order is switched to SHIPPED, the invoicing phase of the process starts including: generation of invoice number, sending invoice notification email, and contacting payment provider. |
| 12 | Forced closure (edge case, optional) | If the warehouse does not send a shipment notification, after 14 days with no update, Checkout assumes that the item was shipped (status ASSUMED SHIPPED). Also after max. 14 days, the billing status PAYMENT RESERVED switches to COMPLETED. In rare cases, it may occur that this forced closure leads to an invoice for an item that was not shipped. In this case, customer service agents can trigger a manual refund via the SCAYLE Panel. Forced closure is an optional process that can be activated on request. |
| 13 | Returned | After Checkout receives a returned item, the shipment status changes to RETURNED. The system then waits 4 hours if additional items get returned (the time frame resets every time a new item gets returned). For each returned set of items, a mail notification is sent. If at least one item is returned (but not all items), the status switches to PARTIALLY RETURNED and PARTIALLY REFUNDED |
Get order data
SCAYLE allows you to retrieve an order by its reference key or ID.
This method can be used to get an existing order.
This method allows including nested resources using the with parameter.
let response = await adminApi.apis.Orders.getOrder({shopKey: shopKey, countryCode: countryCode, orderIdentifier: orderIdentifier});
let order = response.body;
Options
| param name | type | required | Details |
|---|---|---|---|
| with | string | false | Allows to load the following nested resources within this request:
|
Parameters
| param name | type | required | description |
|---|---|---|---|
| id | integer | true | The ID of the order created. Read-only |
| address | OrderAddress | Billing and Shipping address of the customer | |
| basketKey | string | true | A key that uniquely identifies the customer's cart |
| confirmedAt | string | Timestamp when the order was confirmed | |
| contacts | OrderContact | Collection of contacts | |
| cost | OrderCost | true | Total cost of the order that includes tax, VAT, etc |
| currencyCode | string | true | ISO 4217 currency code |
| customer | Customer | Details about the customer account | |
| shopCountry | ShopCountry | Country of the shop as ISO 3166 alpha 2 country code | |
| invoicedAt | string | Timestamp when the invoice is sent | |
| createdAt | string | Timestamp when the order is created | |
| updatedAt | string | Timestamp when the order is updated | |
| items | OrderItem | Collection of items ordered | |
| legacyCustomData | array | Custom data added to the order (legacy feature) | |
| membershipDiscount | OrderMembershipDiscount | Membership discount information | |
| packages | OrderPackage | Details for the package(s) part of the order | |
| payment | OrderPayment | Payment details | |
| publicKey | string | Public reference set by the client to display to customers in account areas and transactional emails | |
| referenceKey | string | true | External order reference set by the client to integrate a third-party system |
| shipping | OrderShipping | Shipping details | |
| status | string | true | Status of the order, e.g., invoice_completed |
| detailedStatus | OrderDetailedStatus | true | Detailed status of the order |
| vouchers | OrderVoucher | Applicable voucher and its details | |
| loyaltyCard | OrderLoyaltyCard | Loyalty card information |
Get by Reference Key
This endpoint is not shop country scoped, but the shop country, identified by shopKey and countryCode, is still needed.
Get an order by reference key:
let response = await adminApi.apis.Orders.getOrder({shopKey: 'ms', countryCode: 'DE', orderIdentifier: "key=my-key"});
let order = response.body;
console.log(order.id);
Get with Legacy Custom Data
Get an order with legacy custom data:
let response = await adminApi.apis.Orders.getOrder({
shopKey: 'ms',
countryCode: 'DE',
orderIdentifier: "key=my-key",
with: 'legacyCustomData'
});
let order = response.body;
console.log(order.legacyCustomData);
