Initialize Checkout (hidden)

Step 1: Load Configuration

Endpoint: GET /api/co/v3/state/config

Before initializing the checkout, you need to call the Config Endpoint to retrieve essential backend configurations.

This step provides information such as:

Available billing and shipping countries
Optional translations (if configured)
Other setup data required for address and localization handling

📝 Note:
Translations are only returned if they are configured in the backend. If not, it is the client’s responsibility to handle all translation logic on the frontend.

⚠️ Important:
You must restrict address input to the countries listed in the availableBillingCountries and availableShippingCountries returned by the config response.

Step 2: Start or Continue a Checkout Session

Endpoint: PUT /api/co/v3/state

This step initializes a new checkout session or resumes an existing one. It is essential for linking a basket to the checkout flow and enabling subsequent steps like setting addresses and selecting payment methods.

To authenticate the request, you must send a JWT (JSON Web Token) in the request body, signed with HS256 using your shop’s secret.

🔐 JWT Requirements

The JWT payload must include the following fields:

Property	Required	Description
`iss`	✅	Issuer (your shop's base URL)
`aud`	✅	Audience (SCAYLE environment URL)
`iat`	✅	Issued at timestamp (UNIX)
`nbf`	✅	Not before timestamp (UNIX)
`exp`	✅	Expiration timestamp (UNIX)
`basketId`	✅	ID of the current basket
`customData`	❌	Optional custom data

Example JWT Payload:

{
  "iss": "https://scale.dev",
  "aud": "https://scayle.dev",
  "iat": 1744699678,
  "nbf": 1744699678,
  "exp": 1744706883,
  "basketId": "1404-b0d2336c-74cd"
}

Behavior on Session Resume

If the customer has a previously confirmed order, the following will be pre-filled automatically:

Order addresses (billing & shipping)
Last selected shipping option
Last selected payment option

⚠️ Important:
Payment options will only be available after a valid billing address has been set. Ensure that step is completed before offering payment choices to the user.

Step 3: Listen for Updates

Endpoint: GET /api/co/v3/state

Once the checkout session is initialized, you should periodically fetch the current state of the ongoing order using the GET state endpoint.

This state object reflects the most up-to-date checkout data and is central to managing:

Item availability and stock updates
Shipping and payment option availability

🔁 When to Fetch State

You should regularly poll the state endpoint in scenarios such as:

When a customer is idle on the checkout page for an extended period

⏱️ Tip: Consider a short polling interval (e.g., every 15–30 seconds)