Handling Add-On Subscriptions
Add-On Subscriptions: The Full Lifecycle
Background reading
Before you build anything, read the Add-Ons Pricing article on Salla Developers. It covers how to configure add-on pricing for your app from the Partners Portal, separate from your main plan pricing.The two types
One-time (once)
A single charge. You'll receive app.subscription.started once, and that's it, no renewal cycle exists for this type. Use that event to provision the feature for the merchant right away. The merchant can still cancel at any point, which sends app.subscription.canceled the same way it does for any other add-on.Partner-recurring (external_recurring)
You own the billing cycle. Salla doesn't attempt a wallet deduction automatically, and doesn't store an end_date for it. You bill the merchant again yourself, on the monthly or yearly cadence they agreed to, and you'll receive app.subscription.renewed each time that succeeds.item_type before acting on any of these webhooks. The same event names fire for your app's base plan too. Skip the check and an add-on event can get processed as a base plan event, granting or revoking the wrong thing.The full lifecycle
Step by step
Started
Fires once, the moment the merchant completes the purchase, for both one-time and partner-recurring add-ons. The event you'll receive is Provision the feature for the merchant immediately when this arrives. If the add-on involves a countable entitlement, credits, seats, requests, read If the add-on is one-time,
app.subscription.started.quantity from the payload and record it on your side. Salla doesn't track usage. Whatever the merchant has used or has left is your responsibility from this point forward.app.subscription.started is the only event you'll ever get for it. There's no renewal cycle to track, stop here.Triggering Renewal
For partner-recurring add-ons, nothing renews on its own, you're the one who makes the call. No webhook tells you a cycle is due, that part is entirely on you to track.The merchant agreed to a monthly or yearly cadence when they bought the add-on. Salla isn't holding an When a cycle is due, call: The Don't call this before the cycle is actually due, and don't call it more than once for the same cycle. It's rate limited specifically to catch that, calling it early or repeatedly is what causes a double charge.
end_date to remind you, so track each merchant's next due date yourself based on when they started and the period they signed up for.POST https://api.salla.dev/admin/v2/apps/subscriptions/{subscription_id}/renewsubscription_id here is the old subscription ID, the one from the merchant's most recent webhook event. Use the merchant's bearer token.Renewal result: success or failure
The call you just made resolves one of two ways.
Success
Failure
The subscription is renewed for the period the merchant chose, monthly or yearly, and a new Key your entitlement records on
subscription_id is generated. The old subscription record moves to renewed status, the new one is active. You'll also receive app.subscription.renewed as confirmation, it arrives with the new subscription_id, update your entitlement to point at it.(merchant, item_slug), never on subscription_id. The ID changes every cycle, the merchant and the add-on slug don't. And don't revoke access when you see renewed, it means the cycle closed successfully, not that anything ended.Canceled
The merchant can end the add-on at any point, regardless of which type it is, not just after a renewal. The event is Revoke access as soon as it arrives. The merchant already knows why, no explanation needed on your end.
app.subscription.canceled.Confirming where things actually stand
GET https://api.salla.dev/admin/v2/apps/{app_id}/subscriptions| Status | Meaning |
|---|---|
active | The add-on is live, the merchant has access. |
renewed | This specific record was replaced by a new one this cycle. Access didn't end, it continued on the record that replaced it. |
Modified at 2026-08-19 19:48:55