Recurring Payment App Usage - Salla Merchants APIs

This section provides a practical overview of how to implement and use Recurring Payments within your integration. It explains how to embed the required App Snippet to enable recurring billing functionality on the storefront or creating subscription orders via Create Order API

1- Storefront Implementation

App Snippet Requirement

Using Recurring Payments on storefront requires an App Snippet to inject the client‑side logic that adds subscription items via the Salla Twilight SDK. Your snippet should:

Render the subscription UI (plan selector, interval, etc.).

Use the Twilight SDK Add Item method to add the product with a recurring payload.

Enforce the one‑item cart rule when a subscription is present.

Read plan/config values from App/Store Settings to build the payload.

The implementation leverages the Salla Twilight SDK to inject subscription metadata into the cart flow, transforming regular product purchases into recurring subscriptions with defined billing intervals and terms.

Here goes some screenshots of where you may find the App Snippet from the Salla Partners Portal

Implementation Guide

Step 1

App Snippets provide the client-side logic necessary for recurring payments. The snippet intercepts the add-to-cart action and appends subscription metadata to transform the purchase into a recurring payment.

Step 2

The developer must add/modify a Subscribe button in the product page, or any page, using the App Snippet.

Step 3

Deploy your App Snippet through the Salla Partner Portal and test the subscription flow on a development store before releasing to production.

2- Server-to-Server API Implementation

This approach does not require any modifications to the storefront, you may use the Orders API to create an order with subscription items.

When creating subscription items through Orders API, ensure the followings:

1- payment.status should be set to pending_payment
2- payment.method should be set to credit_card
3- payment.accepted_methods should only contain credit_card
4- payment.recurring should be set to true

Set the products.recurring object as per your needs.

{
    "customer": {
        "id": 1209983424,
        "name": "new name",
        "mobile": "+966566666666",
        "email": "mail@mail.com"
    },
    "receiver": {
        "name": "i am the one",
        "country_code": "SA",
        "phone": "966566666666",
        "email": "email@mail.com",
        "notify": false
    },
    "delivery_method": "shipping",
    "branch_id": 203948803,
    "courier_id": 1433878184,
    "ship_to": {
        "country": 1473353380,
        "city": 1939592358,
        "district": 674989864,
        "block": "Apt. 836",
        "street_number": "8230",
        "address": "24453 Rosalinda Well",
        "address_line": "West",
        "postal_code": "51434",
        "geo_coordinates": {
            "lat": 79.0225,
            "lng": 53.5041
        }
    },
    "payment": {
        "status": "pending_payment",
        "method": "credit_card",
        "accepted_methods": [
            "credit_card"
        ],
        "recurring": true
    },
    "products": [
        {
            "identifier_type": "id",
            "identifier": 892907448,
            "quantity": 1,
            "options": [
                {
                    "id": 1626535321,
                    "value": [
                        "96445177"
                    ]
                }
            ],
            "recurring":{
                "slug": "premium-subscription-plan",
                "interval_unit": "month",
                "interval_count": 12,
                "meta":{
                    "note": "Internal note"
                }
            }
        }
    ]
}

Parameters Reference

Required Parameters

The recurring payment object requires the following parameters to function correctly:

Parameter	Type	Description
`app_id`	integer	Your unique application identifier from the Salla Partner Portal - Optional when using Orders API
`slug`	string	A unique identifier for the subscription plan (e.g., `basic-monthly`, `pro-annual`)
`interval_unit`	string	The unit of time for billing cycles. Accepted values: `day`, `week`, `month`, `year`
`interval_count`	integer	The number of interval units between billing cycles (e.g., 30 days, 1 month)

Optional Parameters

Parameter	Type	Description
`meta`	object	Custom metadata object for storing additional information like plan details, customer notes, or tracking data

Interval Management

For a subscriber with an active subscription for a specific product, a new subscription for the same product cannot be initiated until the current subscription has expired or been terminated.

The partner must not trigger multiple charges for an active subscription within the same billing interval. Each interval represents a single valid billing cycle.

Each subscription item must define its own recurring object. Non-recurring items can coexist in the same cart.

Cart Restrictions

Subscription items have special cart handling requirements:

When a subscription item is added to the cart, all items must share the same subscription interval unit (e.g., month, year) and interval count (e.g., every 1 month, every 3 months). This restriction ensures that subscriptions with different billing intervals cannot be mixed in a single cart.

Once created, subscription parameters (price, interval, plan details) cannot be modified. Changes require cancelling the existing subscription and creating a new one.

Additional Resources

Salla Twilight SDK Documentation

App Snippet Development Guide

Partner Portal Dashboard

Usage

1- Storefront Implementation#

App Snippet Requirement#

Implementation Guide#

2- Server-to-Server API Implementation#

Parameters Reference#

Required Parameters#

Optional Parameters#

Interval Management#

Cart Restrictions#

Additional Resources#