Salla App Billing Flow

Set up how merchants pay for your app and keep a reliable picture of each merchant's plan. Salla owns billing — you react to events and (optionally) read the subscriptions endpoint; you never charge cards yourself. Follow the steps in order; complete each gate before moving on. Steps 1, 2 and 5 perform actions with the Salla Partners MCP; Steps 3–4 and 6 are the runtime logic you write.

Source of truth

Plan state is event-driven — drive it from verified app.subscription. / app.trial. webhooks, then reconcile against the Admin (Merchant) API on https://api.salla.dev/admin/v2 (OAuth, offline_access). Two real endpoints back this skill:

• GET /apps/{app_id}/subscriptions — retrieve the app's subscription statuses + details

for both plans AND addons (filter by itemtype): plan state, entitlements, dates, subscriptionbalance (reconciliation; Step 5). Full OpenAPI schema (source of truth): https://docs.salla.dev/5401098e0.md

• POST /apps/balance — write back the Pay-As-You-Go usage balance (Step 5b).
• POST /apps/subscriptions/{subscriptionid}/renew — for externalrecurring plans/addons

the partner drives each renewal (Salla does not auto-renew them). Take subscriptionid from the subscription webhook; needs offlineaccess. Returns the renewed subscription (itemtype/itemslug/plan*/startdate/enddate/subscriptionbalance/features). Handle the errors: notrenewable, subscriptionnotactive, autorenewdisabled, paymentfailed (403), ratelimitexceeded (429 — once/day). Applies to addons with support_renew: true. (Salla-managed recurring renews automatically — you only receive app.subscription.renewed.) Read the exact request/response schema and the full error-response contract from the live OpenAPI doc — it is the source of truth: https://docs.salla.dev/37396517e0.md (don't hand-code the shapes; mirror the doc).

Confirm payloads and field shapes via the App Events reference (https://docs.salla.dev/421413m0.md) or salla_events action=list before coding. The Salla Partners MCP performs the actions:

Plans vs Addons

Both flow through the same app.subscription. / app.trial. events. This skill owns plans, addons, entitlement gating, and usage billing. Buying addons in-app → salla-addon-purchase. plantype values: free · once (one-time) · recurring (monthly/yearly) · ondemand (Pay As You Go).

Step 0 — Discover

Ask before starting:

1. Which plan types will you offer? (Free, Monthly, Yearly, Trial, One-Time, Pay As

You Go)

1. What does each plan unlock? (the features[] → entitlement mapping)
2. Do you need a free trial before the paid plan?

Step 1 — Define Pricing Plans (publication pricing section)

Plans and addons are defined inside the publication's pricing section — apppublish action=set section=pricing data={…}, then apppublish action=validate. There is no separate pricing endpoint; the Portal's Pricing wizard step is a UI helper over the same section. The publish mechanics are owned by salla-publication-consistency; the pricing data shape is:

• plantype — "free" | "recurring" | "once" | "ondemand" (required; exact API values — no onetime or payasyougo). It selects which fields apply. free is eligibility-gated — only when canhavefreeplan is true (shipping/communication app or the showappfreeplan feature); read it from app details before offering free (→ references/pricing-shapes.md).
• Recurring — plans[] (≤8; 0–4 monthly, 0–4 yearly). Each plan: name{ar,en}, subtitle{ar,en}, price, recurring (free | monthly | yearly | one-time), recommended, iscompareincluded, hidden, initializationcost, discount, additionalfeatures[], promotions[] (max 1), balance (for one-time/ondemand), and id to update a plan in place. Plus the top-level planfeatures[] comparison matrix.
• Once — onetimeprice, onetimeoldprice (> price), planadditional_features[] {key,name,price,adjustable,min,max}. No plans[].
• On-demand — plans[] with balance required + ondemandtype (emails|messages|per-transaction).
• Addons (all types, max 5) — {name,description,price,slug,supportrenew}. name, price, and slug are required on every entry — the server rejects any addon missing one. All prices are in SAR; there is no currency field. Always one-time; supportrenew is the only recurring control: true ⇒ external_recurring (you drive renewals via the renew API; state the cycle in the addon title/description), else once events.
• Trial is top-level: plantrial (days, min 1, capped by max-trial-days — default 7) + trialdescription (30–1000). Churn: unsubscribereward, unsubscribeemail_reward.

Naming traps: plan_type:"recurring" (model) ≠ per-plan recurring:"monthly" (period);
and planadditionalfeatures (top-level, once) ≠ per-plan additional_features (recurring).

Full field tables, types, and server rules: load [references/pricing-shapes.md](references/pricing-shapes.md).

Set this section with apppublish action=set section=pricing, then apppublish action=validate (saves the draft). Full publish flow → salla-publication-consistency.

After the app exists, App details → Custom Plans exposes per-merchant/tailored plans.

Gate: "Plans configured in the publication's pricing section (app_publish action=set section=pricing) and the publication validates clean?"

Step 2 — Set the Webhook URL (app events auto-deliver)

The events are your source of truth — and they are app events (app.subscription. / app.trial.), so the app is subscribed to them by default: Salla delivers all of them to your webhookurl automatically. You do not call sallaevents action=subscribe for any app.* event. The one action here is to set the receiver:

• sallaapps action=connect, appid, webhook_url,

webhooksecuritystrategy: "signature" — point app events at your handler (→ salla-app-lifecycle Step 1 for the full connect + secret-sync recipe).

salla_events action=subscribe is only for non-app (store) events — order., product., customer., cart., store-side shipment.* — that the app wants to react to. Billing rides entirely on app events, so this skill needs no subscribe call.

App events auto-deliver — set webhookurl, then HANDLE them. Every billing event — app.subscription.started, app.subscription.renewed, app.subscription.expired, app.subscription.canceled, and the app.trial.* events — arrives at your webhookurl the moment it fires, whether or not it appears in the salla_events action=list catalog (renewed/expired/canceled aren't even in it). Your job is to HANDLE all of them in your webhook handler (Step 4), not to subscribe to any of them. The App Events reference (https://docs.salla.dev/421413m0.md) lists each as platform-fired.

Gate: "webhookurl set via sallaapps action=connect (app events auto-deliver to it), and the handler covers the full family — app.subscription.started/renewed/expired/ canceled + app.trial. (Step 4)? No salla_events action=subscribe call for any app. event — subscribe is for store events only."

Step 3 — Track Plan State from Events

Security — events grant paid access. A forged or replayed subscription/trial webhook
can hand out (or revoke) paid features. Verify the webhook signature and enforce
idempotency before mutating plan/entitlement state — that transport layer (signature
verification, replay protection, fast 2xx) is owned by salla-webhooks; token/OAuth by
salla-app-auth. Treat an entitlement change as authoritative only from a verified
server event or the reconciled Partners API (Step 5), never a client-reported plan. Keep
entitlement reads/writes behind your own authenticated admin path, and signing secrets and
tokens out of logs.

Wire the events via salla-app-lifecycle. The deltas that matter here:

• Branch on item_type — "plan" updates plan state; "addon" updates addon

entitlements (same payload family; item_slug identifies which addon).

• Trials are the same payload shape — handle app.trial.started/.expired/.canceled

too, or a trial start/expiry falls through and the merchant gets the wrong gating.

• Persist enddate ?? renewdate on started/renewed; mark the subscription

inactive on expired/canceled.

• Skip billing logic when store_type !== "live" (development/demo stores).

Payload fields and full examples → [references/subscription-events.md](references/subscription-events.md). Live docs — App Subscription Webhook Events: https://docs.salla.dev/2213496m0.md ; App Events reference (lifecycle webhooks with payload examples): https://docs.salla.dev/421413m0.md.

Gate: "A demo-store subscription event upserts the stored plan with the right status?"

Step 4 — Handle Renewals, Expiry & Trials

These three are app events — they arrive at your webhook_url automatically (you don't subscribe to any app.* event — see Step 2); your job is to HANDLE them:

• app.subscription.renewed — confirm still active; persist the new

enddate / renewdate. Don't assume the old end date.

• app.subscription.expired — plan lapsed (no renewal). Restrict access; consider a

grace banner.

• app.subscription.canceled — merchant cancelled. Restrict per your policy.
• Trials arrive as app.trial.started / .expired / .canceled (zero-price

plan_type: once). On trial.started enable trial features and record the trial end; on expiry/cancel downgrade. A converting merchant then triggers app.subscription.started.

Drive feature access from the stored status + end_date, not from the moment an event arrives (events can be late or duplicated — be idempotent). Step 5 is your backstop for missed events.

Gate: "Renewal updates end_date; expiry/cancel restricts; trials gate correctly?"

Step 5 — Reconcile via the App Subscription Details API

After downtime (a missed webhook), reconcile with salla_apps action=subscriptions, which calls the real App Subscription Details endpoint:

GET https://api.salla.dev/admin/v2/apps/{app_id}/subscriptions
Authorization: Bearer <access_token>   # OAuth, offline_access

{app_id} is your Salla Application ID (Salla Partners → My Apps → Your App). The call is made with the merchant's access token, so the data[] is that merchant's subscriptions for the app — one entry per active plan/addon. Doc: https://docs.salla.dev/5401098e0.md.

Response (200) — { status, success, data: [...] }, each item a Subscription Detail (where you read plan state, entitlements, and the usage balance). Read itemtype (filter to "plan" for plan state), plantype, startdate/enddate, features[] ({ key, quantity }), and subscription_balance (the usage balance, written via Step 5b). A 403 means the caller lacks permission for this app.

Full response sample + every field's meaning (and the POST /apps/balance shapes): load [references/subscription-api.md](references/subscription-api.md).

Gate: "Reconciliation returns the merchant's current plan + balance and matches your stored state?"

Step 5b — Update the Usage Balance (Pay As You Go)

For on_demand (Pay As You Go) plans, write the merchant's usage balance back to Salla with the real Update Subscription Balance endpoint:

POST https://api.salla.dev/admin/v2/apps/balance
Authorization: Bearer <access_token>   # OAuth, offline_access
Content-Type: application/json

{ "balance": 2399 }

balance (integer) is required. Doc: https://docs.salla.dev/5401099e0.md.

Response (201) — { status, success, data: { message, code } }. Validation error (422) — { status: 422, success: false, error: { code, message, fields: { balance: ["..."] } } }.

Security. Compute the balance server-side from verified usage and POST it only
behind your own authenticated admin path — never from a client-reported value. Read it
back with GET /apps/{app_id}/subscriptions (Step 5) to confirm. (Same trust model as
Step 3.)

Gate: "Balance written via POST /apps/balance and confirmed by re-reading the subscription?"

Addons

Addons are extra purchasables on top of a plan — recurring or one-time — defined in the publish payload's addons array (Step 1). They arrive on the same event family with itemtype: "addon" (itemslug identifies which addon), so you record them and unlock their features[] exactly like a plan. For the in-app purchase UI (embedded SDK Checkout) → salla-addon-purchase.

Entitlement Gating

Merge the active plan's features[] and every active addon's features[] into one entitlement set per merchant. Recompute that set on every app.subscription. / app.trial. event, and gate at feature-use time (look up the stored entitlement set, never the raw event).

Usage Balance (Pay As You Go)

For ondemand plans, meter each billable action against the merchant's subscriptionbalance (what the merchant owes for the app's service): check the remaining balance before the action, decrement as usage occurs, and block (or warn) when exhausted. Read it with GET /apps/{app_id}/subscriptions (Step 5); write it with POST /apps/balance (Step 5b).

Step 6 — Schema & Gating (reference)

subscriptions
  merchant_id      (PK / FK)
  subscription_id
  item_type        'plan'
  plan_name
  plan_type        free | once | recurring | on_demand
  status           active | inactive | trial
  start_date
  end_date
  features         json   // [{ key, quantity }]
  store_type       development | demo | live
  updated_at

Map features[] → entitlements per the Entitlement Gating section above (plan + addon features merged into one set). Full payloads: [references/subscription-events.md](references/subscription-events.md).

Red Flags

Billing events grant and revoke paid access, so a shortcut here either leaks paid features or wrongly locks a paying merchant out. If one of these is your plan, re-read the named step.

Key Resources