The Recurring Payments feature enables merchants and third-party apps to offer subscription billing to customers.This feature provides comprehensive subscription lifecycle management through APIs, allowing you to create, charge, and manage recurring payments seamlessly. It supports full lifecycle operations, including subscription creation, invoicing, payment processing, renewal, and cancellation, using a consistent RESTful architecture.This API is designed for developers integrating recurring billing logic into merchant or third-party apps, ensuring predictable behavior, event-driven updates, and compatibility with existing checkout and payment workflows.
Before You Start#
Your app credentials (Client ID and Client Secret) are required to authenticate API requests through Salla OAuth 2.0. Once your app is authorized, you can obtain access tokens and begin making authenticated requests to the Recurring Payments endpoints.
Enabling Recurring Payments#
By default, Recurring Payments are disabled for all stores. Only merchants or authorized third-party apps can enable this feature.How to Enable Recurring Payments#
Recurring Payments can be enabled programmatically using the Update Setting Slug endpoint in the Merchant API. To activate the feature, update the setting slug payment.recurring to true for the target store using a request call as below:Refer to the following resources for full implementation details:
🔗 Update Setting Slug: Update individual settings. Once enabled, the App can add subscription products to the cart and start processing recurring payments through the Recurring Payments API.
Process Flow#
The following diagrams illustrate the end-to-end flow of the Recurring Payments process, beginning from the checkout page where the merchant’s customer submits payment.They show how the system validates the recurring configuration, processes the payment through the gateway, and emits webhook events to reflect successful or failed charge attempts within the subscription lifecycle.
Subscription Creation Flow#
This diagram illustrates how Salla initiates recurring payments and emits the subscription.created webhook, which returns the subscription_id.Developers must store this subscription_id to use it for upcoming renewal operations.
Recurring Charge Attempt#
This diagram illustrates how Salla processes recurring charge attempts for existing subscriptions, emitting either the subscription.charge.succeeded or subscription.charge.failed webhook based on the payment outcome.Developers should handle these events to update subscription status and billing records accordingly.
General Considerations#
Recurring payments can be automated by implementing a System Scheduler on the partner’s side. This scheduler is responsible for periodically triggering renewal requests for active subscriptions based on their billing cycles.
If a coupon code or store-wide discount is applied at checkout, the subscription price is set to the discounted amount.
All future recurring payments for that subscription will continue at the discounted rate unless the subscription is expired or terminated.
