State Management (hidden)
All transaction-related endpoints in SCAYLE Checkout return a unified state response.
The state is the central container entity that includes key order-related information such as:
- Available payment options
- Available shipping options
- Selected payment and shipping options
- Addresses
- Other relevant order data
By always returning the current state, SCAYLE Checkout can efficiently manage dependencies between different entities. For example, selecting a specific payment option may dynamically disable certain shipping options, ensuring consistency across the checkout flow.
Example Flow
Overview
This document outlines the major entities within the SCAYLE checkout object, describing the purpose of each section at a high level. These entities represent the backbone of customer interaction, shipping/payment setup, and cart content during the checkout flow.
Example state response
{
"customer": {
"data": {
"email": "[email protected]",
"firstName": "Max",
"gender": "m",
"id": 192037,
"lastName": "Mustermann",
"type": "personal"
},
"flags": {
"isGuest": false
},
"groups": [
"vip"
]
},
"isExpressCheckout": false,
"orderOptions": {
"shipping": {
"homeDelivery": [
{
"carrierGroupKey": "dhl",
"carrierKey": "DHL_STD_NATIONAL",
"deliveryEstimations": {
"deliveryDays": {
"maximum": 2,
"minimum": 1
}
},
"deliveryOptionKey": "home_delivery",
"hideDivergingBillingAddress": false,
"isDisabled": false,
"requiresDateSchedule": false,
"requiresTimeSchedule": false,
"returnCosts": {
"minBruttoOrderValueAfterReturns": 0,
"returnServiceCost": 0
},
"serviceCosts": {
"taxAmount": 0,
"taxRate": 0.19,
"withTax": 0,
"withoutTax": 0
},
"shippingOptionKey": "standard_delivery"
}
]
},
"payment": {
"generic": [
{
"configuration": {
"fee": 0,
"initializationData": {
"deviceIdent": {
"id": "ABOUTYOU_9TPUV55AWFX9L_RT",
"token": "91cb33a00567e9563379227db3c5c33d65f4d4c57b6927f5047ecf4a6756df7b"
}
}
},
"constraints": {
"maximumBasketValue": 1000000,
"minimumBasketValue": 400,
"minimumCustomerAge": 18
},
"isDisabled": false,
"paymentOptionKey": "paypal_instant",
"paymentOptionProvider": "paypal",
"serviceCosts": {
"total": 0
}
}
]
}
},
"orderState": {
"addresses": {
"billing": {
"city": "Hamburg",
"country": {
"iso2Code": "DE",
"iso3Code": "DEU"
},
"firstName": "Max",
"hash": "1768071382",
"houseNumber": "28b",
"lastName": "Mustermann",
"salutationCode": "m",
"street": "Domstreet 10",
"zipCode": "20253"
},
"shipping": {
"city": "Hamburg",
"country": {
"iso2Code": "DE",
"iso3Code": "DEU"
},
"firstName": "Max",
"forwardToCollectionPoint": false,
"hash": "1768071382",
"houseNumber": "10",
"lastName": "Mustermann",
"salutationCode": "m",
"street": "Domstreet",
"zipCode": "20253"
}
},
"payment": {
"selected": [
{
"configuration": {
"fee": 0,
"initializationData": {
"deviceIdent": {
"id": "ABOUTYOU_9TPUV55AWFX9L_RT",
"token": "91cb33a00567e9563379227db3c5c33d65f4d4c57b6927f5047ecf4a6756df7b"
}
}
},
"constraints": {
"maximumBasketValue": 1000000,
"minimumBasketValue": 400,
"minimumCustomerAge": 18
},
"isDisabled": false,
"paymentOptionKey": "paypal_instant",
"paymentOptionProvider": "paypal",
"serviceCosts": {
"total": 0
}
}
]
},
"basket": {
"discount": {
"campaign": 0,
"promotion": 0,
"sale": 0
},
"id": "1404-b0d2336c-74cd",
"packages": [
{
"applicableDeliveryOptions": {
"homeDelivery": [
{
"carrierGroupKey": "dhl",
"carrierKey": "DHL_STD_NATIONAL",
"deliveryEstimations": {
"deliveryDays": {
"maximum": 2,
"minimum": 1
}
},
"deliveryOptionKey": "home_delivery",
"hideDivergingBillingAddress": false,
"isDisabled": false,
"requiresDateSchedule": false,
"requiresTimeSchedule": false,
"returnCosts": {
"minBruttoOrderValueAfterReturns": 0,
"returnServiceCost": 0
},
"serviceCosts": {
"taxAmount": 0,
"taxRate": 0.19,
"withTax": 0,
"withoutTax": 0
},
"shippingOptionKey": "standard_delivery"
}
]
},
"carrierGroupKey": "dhl",
"deliveryDate": {
"max": "2025-04-10",
"min": "2025-04-11"
},
"id": 1,
"isAvailable": true,
"items": [
{
"brand": {
"id": 1404,
"name": "DE"
},
"categories": [
{
"id": 2248,
"name": "Jeans"
}
],
"discount": {
"campaign": 0,
"campaignWithoutTax": 0,
"promotion": 0,
"sale": 0,
"saleWithoutTax": 0,
"total": 0,
"voucher": 0,
"voucherWithoutTax": 0
},
"displayData": {
"identifier": {
"label": {
"translationKey": "identifier"
},
"value": "12345678908765432567"
},
"name": {
"label": {
"translationKey": "name"
},
"value": "A pair of jeans."
}
},
"id": "1fb0a167e68e4e697611819f9f970c8e",
"imageUrl": "https://global-dev.cdn.scayle.cloud/75b36bbf3c0c1d5958d05dcfac095679",
"isQuantityChangeDisabled": false,
"merchant": {
"id": 1,
"name": "About You",
"variantId": "12345678908765432567"
},
"name": "A pair of jeans.",
"pdpUrl": "https://global-dev.checkout.api.scayle.cloud/product-22909",
"productId": 22909,
"quantity": 1,
"styleKey": "5512345",
"total": {
"costWithTaxWithDiscount": 1200,
"costWithTaxWithoutDiscount": 1200,
"costWithoutTaxWithDiscount": 1200,
"costWithoutTaxWithoutDiscount": 1200
},
"unit": {
"costWithTaxWithoutVoucher": 1200,
"costWithoutTaxWithoutVoucher": 1200,
"taxRate": 0,
"taxWithoutVoucher": 0
},
"variantId": 42420,
"warehouseId": 1
}
],
"shippingMerchantName": "About You"
}
],
"tax": {
"amount": 7880
},
"total": {
"costCapture": 55200,
"costPaymentServiceCosts": 0,
"costShippingServiceCosts": 0,
"costWithTaxWithMembershipDiscountWithoutServiceCosts": 55200,
"costWithTaxWithVouchersWithServiceCosts": 55200,
"costWithTaxWithVouchersWithServiceCostsWithGiftCard": 55200,
"costWithTaxWithVouchersWithServiceCostsWithoutGiftCard": 55200,
"costWithTaxWithVouchersWithoutServiceCosts": 55200,
"costWithTaxWithoutAbsoluteVouchersWithoutServiceCosts": 55200,
"costWithTaxWithoutPromotion": 55200,
"costWithTaxWithoutVouchersWithoutServiceCosts": 55200,
"costWithoutTaxWithVouchersWithServiceCosts": 47320,
"costWithoutTaxWithVouchersWithShipping": 47320,
"costWithoutTaxWithoutAbsoluteVouchersWithServiceCosts": 47320
}
},
"id": 1427358616,
"shipping": {
"selected": [
{
"carrierGroupKey": "dhl",
"carrierKey": "DHL_STD_NATIONAL",
"deliveryEstimations": {
"deliveryDays": {
"maximum": 2,
"minimum": 1
}
},
"deliveryOptionKey": "home_delivery",
"hideDivergingBillingAddress": false,
"isDisabled": false,
"requiresDateSchedule": false,
"requiresTimeSchedule": false,
"returnCosts": {
"minBruttoOrderValueAfterReturns": 0,
"returnServiceCost": 0
},
"serviceCosts": {
"taxAmount": 0,
"taxRate": 0.19,
"withTax": 0,
"withoutTax": 0
},
"shippingOptionKey": "standard_delivery"
}
]
},
"signature": "578dfabf64eab60cfa7a16858473020f"
}
}
customer
Captures key identity and segmentation details of the user engaging with the checkout, including name, email, type (e.g., personal or business), guest status, and assigned customer groups (e.g., VIP). This section supports both personalized and guest checkout flows and may influence available payment/shipping options or discounts.
orderOptions.shipping
Defines the available shipping options for the current session. Includes carrier options (like DHL), delivery time estimations, service costs, and delivery conditions (e.g., whether scheduling is required). It functions as the menu of possible shipping services that can be offered to the customer at checkout.
orderOptions.payment
Lists all available payment methods based on the current basket and customer profile. Each option contains eligibility constraints (like basket value or customer age), service fees, and required configuration data (e.g., tokens for third-party gateways). This section ensures the checkout process only displays payment methods that are valid for the current order context.
orderState.addresses
Holds the customer’s selected billing and shipping addresses. Each address includes standard details like name, street, zip code, city, and country codes. It also supports differentiating between billing and shipping addresses and enables functionality such as delivery to collection points or home addresses.
orderState.payment
Indicates the selected payment method(s) for the transaction. Mirrors the structure of orderOptions.payment, but represents what the customer has chosen. This section is used to trigger payment processing and ensure proper handoff to the chosen payment provider.
orderState.shipping
Represents the currently selected shipping method(s). It reflects the customer’s choice from the list provided in orderOptions.shipping, capturing delivery preferences, estimated timeframes, and associated costs. This is critical for fulfillment decisions and calculating total order cost.
orderState.basket
Encapsulates the contents of the shopping cart at checkout, including items, applied discounts, and total cost breakdowns. It also includes delivery options per package and tax calculations. This is the most complex and central object in the checkout flow, as it defines what is being purchased and at what cost.