Manage Recurring App Subscriptions - Salla Merchants APIs

This section outlines the core endpoints for managing subscription-based orders through the Recurring Payments API. It explains how to initiate and process recurring payments, charge existing subscriptions, and manage their lifecycle.
These endpoints form the foundation of Salla’s recurring billing workflow, enabling seamless integration and automation within your application.

Payment and Subscription Creation

When a cart includes one or more recurring items, the checkout process automatically performs the following actions:

Initiates a subscription creation request with the payment gateway.

Processes the first payment transaction.

Generates the initial order.

Emits a webhook event (subscription.created).

The subscription becomes active immediately after the first successful charge.

Charge an Existing Subscription

You can programmatically trigger a new charge for an active subscription. Refer to the Charge a Subscription endpoint for complete endpoint details.

✅ On Success

❌ On Failure

A new cart and order are created for the subscription items.

An invoice is created.

The payment is processed through the configured gateway.

A webhook event (subscription.charge.succeeded) is emitted.

Update Subscription Payment Method

To update the payment method used while creating a subscription payment, you may use the Update Payment Method Endpoint

✅ On Success

❌ On Failure

A new cart and order are created for the subscription items with pending_payment status.

A payment link is returned in the response.

Customer completes the payment through new Credit Card

Order status is updated and subscription is updated with the new payment method

A webhook event (subscription.updated) is emitted.

When updating the payment method, the full subscription amount is charged to the new card provided by the customer.

New Subscription (Using Existing Payment Authorization)

The Modify Subscription operation allows you to create a new subscription while reusing the payment authorization of an existing active subscription.

This flow is useful for several scenarios, including:

Updating subscription item prices or quantities

Migrating a customer to a new subscription plan

Adding additional recurring items to a customer

Creating a replacement subscription while keeping the original payment authorization

Despite the name, this operation does not update the existing subscription.
Instead, it creates a new subscription and charges it using the previously authorized payment method.

To perform this action, use the Create Order endpoint and include the existing subscription ID as a payment reference.

Required Request Body Fields

Property	Value
`payment.status`	"paid"
`payment.method`	"subscription"
`payment.reference_id`	existing subscription id

Update any other attributes that you'd like to, including the recurring object per product.

Process Flow

✅ On Success

❌ On Failure

A new cart and order are created for the subscription items with pending_payment status.

The total amount is deducted using the payment method defined for existing subscription id

A new order and subscription is created and subscription id is returned in the response

A webhook event (subscription.created ) is emitted.

This operation creates a new subscription and charges the full subscription amount.

The previous subscription remains active.

If you want to keep only one active subscription, you must explicitly cancel the old one using the Cancel Subscription endpoint.

Cancel a Subscription

To stop future recurring charges, you can cancel an active subscription at any time. Refer to the Cancel a Subscription endpoint for full details. Once cancelled, a subscription cannot be reactivated. The customer must initiate a new subscription if they wish to continue service.

Manage Subscriptions

Payment and Subscription Creation#

Charge an Existing Subscription#

Update Subscription Payment Method#

New Subscription (Using Existing Payment Authorization)#

Required Request Body Fields#

Process Flow#

Cancel a Subscription#

Payment and Subscription Creation

Charge an Existing Subscription

Update Subscription Payment Method

New Subscription (Using Existing Payment Authorization)

Required Request Body Fields

Process Flow

Cancel a Subscription