Overview

Set up recurring payments with Solidgate subscriptions to create products, configure trial periods, and manage billing frequencies

Solidgate subscription feature connects customers to your product or service, defines recurring payment frequency, and specifies what they are subscribing to.

In the initial stages of working with the Solidgate subscription feature, merchants must manually create a product and its associated price following the subscription rules in the SolidgateHub. This process is part of product and price management. After creating the product, it gets a unique product_id. The unique identifier should be passed to initialize the subscription payment via one of the Solidgate’s checkout solutions, cardAPI v1, and aPMAPI v1 payments.

Solidgate subscription logs are stored for the last 60 days. If you need older data, contact us.

Please note that only the following APMs support subscription payments:
PayPal, Alipay, GCash, MB WAY, Mercado Pago, UPI, WeChat Pay, Pix, and SmartPix.

When creating your subscription product, you can choose to offer it with or without a trial. This helps you meet customer needs and shape their first experience. Solidgate provides the following options:

Without trial
Subscription starts immediately with regular billing. You define the recurring amount, currency, and payment frequency.
Example: A video streaming service charges $9.99 monthly with no trial period.
With a free trial
Subscription includes a zero-cost trial period before regular billing begins. You specify the recurring amount, currency, and payment frequency to apply after the trial ends.
Example: A fitness app offers a 14-day free trial and a $19.99 monthly fee after the trial.
With a paid trial
Subscription starts with a one-time charge for the trial period before transitioning to regular billing. You define the trial amount, currency, and details of recurring charges that apply after the trial.
Example: An online course platform offers a 7-day paid trial for $5, followed by a recurring fee of $29.99 monthly.

Trial settings can be modified via Hub or by the update a productAPI v1 method after a subscription is active, but you cannot add or remove a trial once the subscription has started.

Subscription process

To initiate a subscription for a customer, merchants follow a streamlined process that involves product creation, payment processing, and subscription initialization.

The merchant creates a product and receives a product_id.
The merchant passes the product_id in the request. To create a subscription, include customer_account_id, a required parameter for subscription initialization.
- via one of the checkout solutions
- via cardAPI v1 or APMAPI v1
- via resign using an existing recurring token
Solidgate obtains the price and payment configurations from the product configuration and sends the payment for processing.
After successful payment processing and subscription creation, the merchant receives the subscription_id and a notification regarding the subscription creation, which also appears among subscription events.

The merchant can use the subscription_id to perform further operations on the subscription, such as changing the product, cancelling, or resuming the subscription. The subscription_id also serves as a key to locating the specific subscription in the Hub.

Solidgate system restricts the creation of multiple active subscriptions for the same customer_account_id and product_id within a channel. To prevent double charging, Solidgate disallows duplicate subscriptions by declining these attempts with a 2.14 Subscription error, ensuring a single subscription per product.

To track the number of passed billing periods, each subscription has a term number, subscription_term_number, representing the sequential billing period excluding trial periods. This number increments when a new billing period begins or when the subscription is upgraded or downgraded with a billing period change.

For example, if a customer upgrades from a monthly to a yearly plan, the term number increments and a new billing period starts, with any unused credit from the previous period applied. However, upgrading from one monthly product to another monthly product keeps the same term number, as the billing period length remains unchanged.

Billing period

Solidgate subscription billing follows calendar billing. A billing period of one month equals one calendar month and may contain 28, 29, 30, or 31 days, depending on the month.

Recurring charges are processed on the day of the month that matches the subscription start date, taking into account the number of days in the current month.

For example:

If a customer subscribes on January 1, the next charge occurs on February 1.
If a customer subscribes on January 31, the next charge occurs on February 28 (or 29 in a leap year).

Subscription with free trial

Merchants may choose to offer customers a trial period for their products at no cost at all. To provide free trials, they can use zero-amount authorization or the auth-void process. Understanding the nuances of these approaches helps manage customer expectations and ensure a smooth start to the trial period.

These approaches help merchants offer trial periods effectively. They create a positive customer experience and let merchants verify payment methods without charging customers upfront.

Subscription statuses

Value	Description
`pending`	Subscription is awaiting confirmation of successful payment. Depending on whether the initial payment is approved or declined, the pending subscription transitions to either an `active` or `expired` status.
`active`	Payment is successful, the subscription is active, and the customer is billed according to its set interval.
`paused`	Billing for the subscription is halted during the specified pause period or until manual reactivation.
`cancelled`	Subscription is cancelled, and the customer is unsubscribed.
`redemption`	For subscription products with retry strategies applied, if a recurring payment is declined due to a certain error code, the subscription enters a redemption period. If all retries fail, the subscription is `cancelled`. However, if any of the attempts on the retry are successful, the subscription status changes to `active`.
`expired`	Subscription is inactive due to payment failure or lack of gateway response within the expected timeframe.

A pending subscription signifies awaiting confirmation of a successful initial payment. Depending on whether the initial payment is approved or declined, the subscription transitions to either an active or expired status.

An expired status means the initial payment for a pending subscription has failed. Subscriptions can also move from pending to expired. It happens when Solidgate receives no response from the gateways within a defined timeout to determine if the order is successful or failed.

An active subscription indicates that the customer continues to pay for the product on a recurring basis.

For subscription products in retry mode, if a recurring payment is declined due to a specific error code, the subscription enters a redemption period. During this period, retry attempts are made to collect the invoice. If retry attempts fail or the customer unsubscribes, the subscription status changes to cancelled. However, if the retry attempt succeeds and the customer keeps the subscription, its status changes to active. Subscriptions also get the cancelled status automatically when you set up the alert-based cancellation rules, which allow merchants to balance risk management.

If a subscription is paused, billing is halted during the specified pause period or until manual reactivation. This means no charges are applied to the customer until the pause period ends or the subscription is manually reactivated.

To use the new pending and expired statuses, activate them in the Solidgate Hub. Navigate to Billing > Billing settings > General settings and enable Extended subscription statuses and webhooks.

Please note that the new statuses are activated at the account level, not per individual channel. Additionally, if you activate the new statuses without subscribing to the extended Subscription updates event, you do not receive webhooks related to these statuses. However, once the new statuses are activated, you still see the updated subscription statuses in the Hub and responses.

After performing a subscription statusAPI v1 request, you receive information about the last invoice for the subscription and the order status ID. This information can later be used to verify the external order ID in the SolidgateHub.

Invoice statuses

An invoice status reflects the current state of the payment for the customer’s subscription. It shows whether the payment is being processed, completed, or failed.

Value	Description
`processing`	The invoice has been generated, and the customer’s payment is in progress.
`retry`	A payment attempt has resulted in a failure, and another attempt is in progress.
`success`	The payment was successfully received, and the invoice is paid.
`fail`	All payment attempts were unsuccessful, resulting in an unpaid invoice and either a cancelled or expired subscription.

Payment attempt limit

There is a specific limit on the number of payment attempts that can be in a processing state for a single subscription. The purpose of the payment attempt limit is to give customers more flexibility when signing up for a subscription and ensure effective subscription management.

When customers sign up using the same customer_account_id and product_id combination, they can have up to three payment attempts in the processing state at once. This means they can try up to three payment methods for the first charge. For example, if a customer’s preferred payment method is temporarily unavailable, they can easily try an alternative without being limited to a single attempt.

This approach ensures:

Better conversion rates for the initial payment while keeping the number of pending charges manageable.
Prevention of unnecessary pending charges and potential chargebacks. If one payment attempt is stuck in processing while another is successfully completed, the stuck payment attempt is automatically refunded.
Handling of duplicate charges, such as those due to delayed order processing. Any extra payment is identified and refunded, which mitigates the probability of chargebacks and confirms only one successful charge per subscription sign-up.

Enforcing this limit enhances the overall subscription experience and reduces potential payment issues for both customers and businesses.

Discounts

The predefined and the direct flows are the primary ways to apply discounts to customer subscriptions.

Predefined flow

In this method, you can add a coupon directly to a customer’s order. The discount is applied automatically, without the need for a coupon code.

For example, you want to offer a time-sensitive deal. You provide a 30% discount for the first three months if a payment is completed within 10 minutes. Instead of adjusting product prices, create a coupon and apply it directly to the customer’s order.

Integrate this flow into your checkout process with the predefined coupon flow in Payment Form.

Direct flow

In this approach, customers can redeem coupon codes to get discounts on their subscriptions. They can enter the code at checkout to receive the discount.

For example, you create a coupon offering a 15% discount for the next two months and generate a coupon code for it (SUMSALE15OFF). Customers receive this code via email or another notification channel. The checkout page includes a designated field where customers can enter the code to apply the discount.

Integrate this option into your checkout process with the direct coupon flow in Payment Form.

Discounts with trial options

For products that feature a trial period, discounts from coupons are not applied to the trial price. Instead, the discount takes effect on the subsequent recurring payment.

In situations where the expiration date of a coupon precedes the next recurring payment, the system preserves the discount for that particular payment.

For example, a product costs $20 and offers a 1-month trial. If a once-duration coupon expires in 20 days, its discount applies to the first payment after the trial, regardless of expiration.

Coupons and subscription lifecycle

Understanding how coupons behave across the subscription lifecycle helps navigate billing scenarios.

Paused subscriptions
When a subscription is paused, the coupon stays attached to it. After you resume the subscription, the discount remains active. The system checks coupon validity when the next billing period starts. If the coupon has expired by that time, the discount no longer applies.
Cancelled and restored subscriptions
When a subscription is cancelled, the coupon associated with it becomes inactive. If the subscription is restored, it resumes at its original price. Optionally, a new discount can be applied by providing the coupon_id or coupon_code. If the subscription had a previous discount, it is replaced with the new one.
Mid-cycle coupon application
Coupons take effect starting from the next billing period. If a coupon is applied mid-cycle, the current invoice remains unchanged, and the discount applies to the next invoice.

Handle errors

Identify common errors related to subscriptions, understand their causes, and learn how to resolve them.

Error	Reasons	Recommended action
2.14 Subscription error	Customer already has an active subscription for this product, multiple invoices are in a processing state, or product ID is incorrect.	Check the customer’s active subscriptions for duplicate product IDs. Review the number of invoices in the processing state.
3.11 Recurring payment cancelled	The customer or card issuer has cancelled recurring payments for this payment method.	Do not retry payments and contact the customer for subscription cancellation reason.

Looking for help? Contact us

Stay informed with Changelog