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.status for 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	Only full order cancellations result in item status 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

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.

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: legacyCustomData items.legacyCustomData customer.legacyCustomData

param name

type

required

Details

with

string

false

Allows to load the following nested resources within this request:

legacyCustomData
items.legacyCustomData
customer.legacyCustomData

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