1. Checkout Module
Salla Platform Docs
  • Embedded SDK
    • Overview
    • Getting Started
    • Create an Embedded App
    • Authentication
    • App Design Guidelines
    • Installation
    • Playground
  • Auth Module
    • Get Token
    • Client Introspect
    • Refresh Token
  • Page Module
    • External Redirects
    • Navigation
    • Set Page Title
  • Nav Module
    • Create Navbar Action
    • Listen for Navbar Actions
    • Clearing Navbar Actions
    • Add Navbar Item
    • Update Navbar Item
    • Listen for Navbar Item Click
    • Remove Navbar Item
  • UI Module
    • Confirm Dialogs
    • Toast Notifications
    • Loading States
    • Breadcrumbs
  • Checkout Module
    • Create Checkout
    • Get App Add-ons
    • Subscribe for Payment Result
    • Server-Created Checkouts
  • Endpoints
    • Create Checkout
      POST
    • Get Checkout
      GET
    • Token Introspect
      POST
  • Resources
    • Support
    • Common Examples
  • Report Builder
    • Overview
    • Getting Started
    • JMESPath Tutorial
    • Understanding the Report Lifecycle
    • Salla Reports Examples
    • Set up Store data using merchant APIs
    • Report Types
      • Unit
      • Bar
      • Breakdown
      • Calendar
      • Distribution
      • Pipe
      • Plot
      • Ranking
      • Summary
      • Agrid
    • APIs
      • Token Introspect
  • App Onboarding
    • Overview
    • Get Started
    • Interfaces and Responses
    • Example
  • Schemas
    • Checkout
Merchant
Merchant
  • Merchant API
  • Embedded SDK
  • Salla OAuth 2.0
Storefront
Storefront
  • Twilight (React)
  • Twilight SDK
  • Web Components (Deprecated)
  • Ecommerce Events
  • Component Bundle
  • Checkout APIs
  • Twilight Engine (Deprecated)
  • Change Log
App Functions
Partner APIs
Partner APIs
  • App API
  • Shipments & Fulfillment APIs
  • Salla AWB
  • Recurring Payments API
  • Billing System Salla partners
  • Communication Apps
Dev Tools
Dev Tools
  • Partners Agent Kit
  • Salla Apps Playbook
  • Salla CLI
Merchant
Merchant
  • Merchant API
  • Embedded SDK
  • Salla OAuth 2.0
Storefront
Storefront
  • Twilight (React)
  • Twilight SDK
  • Web Components (Deprecated)
  • Ecommerce Events
  • Component Bundle
  • Checkout APIs
  • Twilight Engine (Deprecated)
  • Change Log
App Functions
Partner APIs
Partner APIs
  • App API
  • Shipments & Fulfillment APIs
  • Salla AWB
  • Recurring Payments API
  • Billing System Salla partners
  • Communication Apps
Dev Tools
Dev Tools
  • Partners Agent Kit
  • Salla Apps Playbook
  • Salla CLI
Salla - Opensource
Salla - Developers Community
  1. Checkout Module

Create Checkout

The create method initiates a native checkout flow within the Salla Merchant Dashboard. It opens the payment drawer where the merchant can review items and complete the purchase.

Usage#

You can pass a single item or an array of items for multi-item checkout, or the checkout_id of a checkout your backend created (needs @salla.sa/embedded-sdk 0.2.7 or later).
Single Item
Multiple Items
Server-Created Checkout
With Context
Purchase a single addon.

API Reference#

embedded.checkout.create(input, config?)#

ParameterTypeRequiredDescription
inputCheckoutItem | CheckoutItem[] | CheckoutByIdInputYesA single item or array of items to purchase, or { checkout_id } to open a server-created checkout.
configCheckoutCreateConfigNoOptional configuration.

CheckoutItem#

PropertyTypeRequiredDefaultDescription
type"addon"Yes-The item type. Currently only "addon" is supported.
slugstringYes-The unique slug identifier of the addon.
quantitynumberNo1Number of units to purchase.

CheckoutByIdInput#

PropertyTypeRequiredDescription
checkout_idstringYesThe id returned by POST /admin/v2/checkouts, as a string (String(id)). Non-empty, at most 64 characters, letters, digits, _ and - only.
Pass checkout_id alone: it cannot be combined with addon items, and context goes in the second argument.

CheckoutCreateConfig#

PropertyTypeRequiredDescription
contextunknownNoDeveloper-defined data persisted across 3DS redirects. Returned in onResult.

Validation#

The SDK validates all items before sending the checkout request. Invalid input throws an error immediately:
ConditionError Message
Empty array"At least one item is required"
Missing or empty slug"Item at index N must have a valid slug"
Missing or empty type"Item at index N must have a valid type"
For { checkout_id }, create() throws an error with code INVALID_CHECKOUT_INPUT before anything is sent when:
ConditionError Message
checkout_id empty or not a string"checkout_id must be a non-empty string"
checkout_id longer than 64 characters"checkout_id must be at most 64 characters"
checkout_id has other characters"checkout_id may only contain letters, numbers, '_' and '-'"
checkout_id combined with type, slug, quantity, item or items, or passed inside an array"checkout_id cannot be combined with item or items"
context inside the first argument"context must be passed as the second argument (config.context)"

Results for a Server-Created Checkout#

The result arrives through onResult() like any checkout, with the checkout_id echoed:
If the checkout is not open on this store (unknown ID, already paid, or replaced by a newer checkout with the same reference_id), the result is { success: false, status: "failed", error: { code: "CHECKOUT_NOT_FOUND" } }.
Paid without a redirect: { success: true, status: "paid", order_id }. Drawer closed: { success: false, status: "cancelled" }.
If the checkout cannot be opened or the payment fails in the drawer, the result is { success: false, status: "failed", error: { code: "CHECKOUT_ERROR" } } (or the code the dashboard returned).
3DS return: when the payment needs a 3DS redirect, the merchant returns to https://s.salla.sa/embedded/app/{app_id}?paid=1&legacy=0 (?paid=&legacy=0, with an empty paid, when the payment failed). That URL opens your app's default embedded page (your first embedded page), not the page that opened the drawer. onResult() fires there with status: "paid" (or "failed"), your context and the checkout_id; the return URL carries no order_id, so read it with GET /admin/v2/checkouts/{id}. Register onResult() on your default page and use context to route the merchant back.
status in onResult() is a hint for the UI, never proof of payment. Fulfil only from the app.checkout.paid App Event, or after your backend reads status: "paid" from GET /admin/v2/checkouts/{id}.

Complete Example#

💡
Best Practices
Register onResult First: Always set up your result listener before calling create() to avoid missing the response.
Validate Slugs: Use getAddons() to retrieve valid addon slugs before calling create(). The checkout will fail if a slug doesn't match any available addon.
Server-Created Checkouts: Compute the amount and create the checkout on your backend; the embedded app only passes checkout_id: String(id).
Context for Navigation: If your app has multi-step flows, pass the current route in context so you can restore it after a 3DS redirect.
Modified at 2026-11-08 13:03:01
Previous
Breadcrumbs
Next
Get App Add-ons