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).API Reference#
embedded.checkout.create(input, config?)#
| Parameter | Type | Required | Description |
|---|
| input | CheckoutItem | CheckoutItem[] | CheckoutByIdInput | Yes | A single item or array of items to purchase, or { checkout_id } to open a server-created checkout. |
| config | CheckoutCreateConfig | No | Optional configuration. |
CheckoutItem#
| Property | Type | Required | Default | Description |
|---|
| type | "addon" | Yes | - | The item type. Currently only "addon" is supported. |
| slug | string | Yes | - | The unique slug identifier of the addon. |
| quantity | number | No | 1 | Number of units to purchase. |
| Property | Type | Required | Description |
|---|
| checkout_id | string | Yes | The 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#
| Property | Type | Required | Description |
|---|
| context | unknown | No | Developer-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:| Condition | Error 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:| Condition | Error 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#
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