salla-addon-purchase-embedded

Salla Addon Purchase — Embedded UX

Buying an addon happens inside the embedded app — a native checkout drawer opens in the Salla Merchant Dashboard, not a separate page or external redirect. This skill owns only the purchase UX: list the add-ons, open the checkout, react to the result. Everything after payment — activation, entitlement, renewal — is webhook-driven and owned by salla-addon-purchase.

Tools & MCPs

The in-iframe purchase is an embedded-SDK Checkout call, not an MCP tool — no MCP action runs here.

Hand-off	Skill
SDK init / handshake / No-Chrome	salla-embedded-app
Addon definition, activation webhook, entitlement	salla-addon-purchase
Pricing primitives	salla-app-billing

Prerequisite — a working embedded app

Build the embedded app first via salla-embedded-app (SDK initialized, handshake done, session token verified server-side, No-Chrome). From here on, assume an authenticated embedded session.

Gate: "Embedded SDK initialized and the session token verified server-side?"

The Checkout module

The purchase entry point is the embedded SDK Checkout module — three methods cover the full flow:

embedded.checkout.getAddons() — fetch your app's add-ons (slugs, names, prices). Docs: https://docs.salla.dev/embedded-sdk/modules/checkout/add-ons.md
embedded.checkout.create(input, config?) — open the native checkout drawer. Docs: https://docs.salla.dev/embedded-sdk/modules/checkout/create.md
embedded.checkout.onResult(callback) — hear the payment result (incl. after a 3DS redirect). Docs: https://docs.salla.dev/embedded-sdk/modules/checkout/result.md

These three Checkout-module docs are the source of truth for the frontend purchase cycle. SDK signatures and payloads are version-dependent across @salla.sa/embedded-sdk releases — confirm them against the docs or the package, and don't hardcode prices or URLs. The addon slug is YOUR pre-known identifier — you set it as the addon's slug at publish and match it as item_slug in the subscription webhooks + API — so referencing your own slug directly is expected.

Step 1 — List the app's add-ons (`getAddons`)

Add-ons are defined in the Pricing step of the App Publish form in the Partners Portal. getAddons returns the authoritative list at runtime; the host caches it for ~30 minutes, so repeated calls are cheap.

Source: https://docs.salla.dev/embedded-sdk/modules/checkout/add-ons.md

import { embedded } from "@salla.sa/embedded-sdk";

// embedded.checkout.getAddons(): Promise<GetAddonsResult>
//   GetAddonsResult = { success: boolean; addons?: AddonInfo[]; error?: { code; message } }
//   AddonInfo = { slug; name; price; product_id; product_price_id }
async function loadAddons() {
  embedded.ui.loading.show();
  const result = await embedded.checkout.getAddons();
  embedded.ui.loading.hide();

  if (!result.success) {
    embedded.ui.toast.error(result.error?.message ?? "Could not load addons.");
    return;
  }

  // Render with Salla's design tokens (No-Chrome): name, what it unlocks, price.
  // Each "Buy" wires the addon's slug straight into startAddonPurchase (Step 2).
  result.addons!.forEach((addon) => {
    renderAddonCard({
      name: addon.name,
      price: addon.price,
      onBuy: () => startAddonPurchase(addon.slug),
    });
  });
}

getAddons() resolves (never throws) on network/timeout errors — always handle success: false. Use the returned slug values verbatim in create(); a slug that doesn't match an available addon fails checkout.

Gate: "Slugs and prices come from getAddons(), not hardcoded?"

Step 2 — Open the checkout (`create`) and hear the result (`onResult`)

create() opens the native payment drawer in the Salla Dashboard. The merchant pays inside Salla billing — you never collect payment. Register onResult first (before any create() call) so you don't miss the response, including results delivered after a 3DS redirect reloads the iframe.

Sources: https://docs.salla.dev/embedded-sdk/modules/checkout/create.md · https://docs.salla.dev/embedded-sdk/modules/checkout/result.md

import { embedded } from "@salla.sa/embedded-sdk";

// Register the result listener once, during init — catches post-3DS-redirect results too.
// embedded.checkout.onResult(callback): () => void   (returns an unsubscribe fn)
//   CheckoutResult = {
//     success: boolean;
//     order_id?: string;
//     status: "paid" | "pending" | "failed" | "cancelled" | "success";
//     error?: { code; message };
//     context?: unknown;   // whatever you passed to create()'s config.context
//   }
const unsubscribe = embedded.checkout.onResult((result) => {
  if (result.context?.route) router.push(result.context.route); // restore state after 3DS
  if (result.success) {
    // Checkout completed — show PENDING, do NOT unlock here (Step 3).
    embedded.ui.toast.show("Finishing your purchase…");
  } else if (result.error) {
    embedded.ui.toast.error(result.error.message);
  }
});
// call unsubscribe() on unmount to avoid leaks.

// embedded.checkout.create(input, config?): void
//   input  = CheckoutItem | CheckoutItem[]
//   CheckoutItem = { type: "addon"; slug: string; quantity?: number /* default 1 */ }
//   config = { context?: unknown }   // persisted across 3DS redirects, returned in onResult
function startAddonPurchase(slug: string) {
  try {
    embedded.checkout.create(
      { type: "addon", slug },
      { context: { source: "embedded-upsell" } },
    );
  } catch (e) {
    // create() throws synchronously on invalid input
    // ("At least one item is required", "...must have a valid slug/type").
    embedded.ui.toast.error("Couldn't start checkout");
  }
}

For a basket, pass an array — create([{ type: "addon", slug, quantity: 2 }, …]). type is currently always "addon". Use context to stash the route/step so you can restore it when the iframe reloads after 3DS.

After checkout the merchant is back in the iframe; the session token may have rotated. If a backend API call returns 401, call embedded.auth.refresh() (→ salla-embedded-app) and re-bootstrap.

Gate: "onResult registered before create(), and checkout opened via create() with a real getAddons() slug — not a hardcoded URL?"

Step 3 — Hand off to the webhook to unlock

A success result (or status: "paid") means checkout completed in the iframe — treat it as a UI signal only. The feature unlocks via the activation webhook, owned by salla-addon-purchase (it processes app.subscription.started, item_type: "addon", matched by item_slug, signature-verified and idempotent — transport rules in salla-webhooks).

On a successful result, show a pending state and let the activation flip it:

// inside onResult, on result.success:
embedded.ui.toast.show("Finishing your purchase…");
// when salla-addon-purchase has activated the entitlement, reveal the feature:
embedded.ui.toast.success("Addon activated"); // after entitlement is persisted server-side

Poll/refresh entitlements from your verified backend; reveal the feature once the entitlement is persisted server-side, and keep the pending state until the webhook lands.

Gate: "Result shows pending only; the feature reveals only after salla-addon-purchase persists the entitlement?"

End-to-End (this skill owns the top half)

[embedded page] getAddons() → render offer  (this skill)
      │  merchant clicks Buy
      ▼
checkout.create({ type:"addon", slug })  (this skill — opens native drawer)
      │  merchant pays in Salla billing  (3DS may redirect & reload the iframe)
      ▼
checkout.onResult(result) → pending state  (this skill; token may rotate → embedded.auth.refresh)
      ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
      ▼  (webhook — salla-addon-purchase owns this)
app.subscription.started (addon) → activate entitlement → reveal feature

Red Flags

Tempting thought	Why it's wrong
"`onResult` returned success, so I'll unlock the addon now."	The client result only moves the UI to a pending state — activate the entitlement only on the signature-verified `app.subscription.started` webhook (`item_type: "addon"`), via salla-addon-purchase (Steps 2–3).
"I'll add my own card form / payment step in the embedded page."	Salla owns billing. Open the native drawer with `checkout.create({type:"addon", slug})` — never collect or store payment yourself (The Checkout module / Step 2).
"I'll match the purchased addon by its name or array index."	Match by `item_slug` — the stable identifier you set as the addon's `slug` and receive on every lifecycle event (Step 3).
"I'll trust the client result to track what the merchant owns."	Reconcile entitlement against the server (the webhook + the subscriptions API), not the client `onResult` — the token may even rotate mid-flow (`embedded.auth.refresh`) (Step 3).

Key Resources

Resource	URL / Skill
Embedded SDK setup / No-Chrome	salla-embedded-app skill
Checkout · Get Add-ons	https://docs.salla.dev/embedded-sdk/modules/checkout/add-ons.md
Checkout · Create	https://docs.salla.dev/embedded-sdk/modules/checkout/create.md
Checkout · Subscribe Result	https://docs.salla.dev/embedded-sdk/modules/checkout/result.md
Activation + entitlement lifecycle	salla-addon-purchase skill
Pricing / definition	salla-app-billing skill
`@salla.sa/embedded-sdk`	npm package (Checkout module authority)
Partners Portal	https://salla.partners