Usage

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.

App Snippet Requirement

Using Recurring Payments 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.

Configuration 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
`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.