Overview

Understand how Solidgate subscriptions work, including lifecycle statuses, billing periods, trials, line items, and discount application

Subscriptions let you charge customers on a recurring schedule for access to a product or service. Unlike one-time invoices, subscriptions automatically generate a new invoice each billing cycle and collect payment from a saved payment instrument.

With Subscriptions 2.0, Solidgate provides features that help you manage recurring billing:

Configurable billing periods
Trial management
Discount management with coupons
Automated invoice generation per billing cycle
Revenue recovery for failed payments
Tax calculation based on customer address

How subscriptions work

A subscription connects a customer to a recurring product charge. It holds line items with quantity, pricing, and billing period, and generates invoices automatically until the subscription ends or is cancelled.

Before you can bill someone, you need a customer record. A customer stores identity, address, and tax information and is either an individual (B2C) or a business (B2B). You set the type at creation, and it cannot be changed afterward.

When you create a subscription, you select an existing customer and a product with a recurring price. Each subscription requires exactly one recurring line item. You can add additional one-time items, such as setup fees. When added at creation, they appear on the activation invoice. You can also add one-time items later by modifying the subscription, in which case they appear on the next generated invoice. All items must use the same currency.

Subscription lifecycle

A subscription starts when you create it and Solidgate generates the first invoice. You collect payment to activate it. From there, Solidgate renews billing automatically each cycle. If a payment fails, Solidgate retries before moving to a terminal state. Cancel the subscription at any point to stop future billing when required.

Create subscription

You

Create a subscription using an existing customer and at least one product with a recurring price. Each subscription requires exactly one recurring line item. Add optional one-time items, such as setup fees, that appear on the first invoice. All items must use the same currency. Optionally, configure a trial period at creation.

Solidgate

Creates the subscription in the CREATED status and generates the first invoice automatically.

If a trial is configured, moves the subscription to TRIALING once the trial invoice is processed, and no regular billing occurs until the trial ends. When the trial ends, generates a new invoice for the first regular billing cycle and charges the customer.

Handle first invoice

You

Collect payment through the Payment Form or Payment Link, or charge a saved payment instrument by Guide
Finalize the invoice and charge a saved payment instrument through the Solidgate API. paying the invoice .

Solidgate

Creates the first invoice in DRAFT status and finalizes it to OPEN automatically. The subscription moves to PENDING and waits for payment.

Once payment succeeds, the subscription moves to ACTIVE (or TRIALING if a trial is configured).

Confirm payment

You

Listen for the INVOICE_PAID webhook event. The invoice payload includes the subscription_id . Use it to match the payment to the subscription in your system. You can also listen for SUBSCRIPTION_CREATED , which fires when the subscription record is created and includes a reference to the generated invoice.

Solidgate

On successful payment, moves the subscription to ACTIVE and saves the payment instrument for future renewals.

If the first invoice is voided, the subscription moves to EXPIRED . This applies whether or not a payment was attempted on the invoice.

Provision access

You

Use the SUBSCRIPTION_ACTIVATED webhook event as the trigger to grant your customer access to the product or service.

Solidgate

The subscription is now ACTIVE . Renewals begin automatically at the next billing cycle.

Renew subscription

You

Listen for INVOICE_PAID on each renewal to confirm billing is active and extend access for the next period.

Solidgate

At the start of each billing cycle, generates a new invoice and charges the saved payment instrument automatically.

Discounts are re-evaluated each renewal. A one-time discount is removed after the first renewal. A limited-time discount expires after its configured duration. A forever discount continues to apply.

Handle failed payments

You

This retry flow applies to renewal payments only. If the first payment fails, the activation invoice remains open for another attempt or can be voided. Listen for INVOICE_PAYMENT_FAILED to track failed renewals.

To configure retries for revenue recovery, see smart retries.

Solidgate

Moves the subscription to REDEMPTION and retries the charge at the invoice level.

If a retry succeeds, the subscription returns to ACTIVE . If all retries are exhausted, it moves to UNPAID or CANCELLED , depending on your configuration.

Cancel subscription

You

Cancel immediately or at the end of the billing period. Optionally include a comment for reporting purposes.

Solidgate

Stops all future invoice generation. Solidgate records the request time and the scheduled cancellation time.

This is a terminal state. If you need to resubscribe, create a new subscription.

Via API

Send a request to the get subscription API v2 endpoint with the subscription ID. Optionally include channel_id for multi-channel setups. The response returns the full subscription object, including status, line items with billing period and product details, trial information, cancellation details, discount, the latest invoice ID, and the next_billing_at timestamp that indicates when the next renewal charge is scheduled.

Via Hub

To view a subscription

Go to Billing > Billing 2.0 > Subscriptions.
Click on the subscription ID to open the details page.

The details page shows the subscription status, customer, line items, billing period, trial information, payment instrument, discount, and event history.

Manage subscriptions

Subscription statuses

Every subscription progresses through a defined set of statuses.

Status	Description
Created	The subscription record exists and the first invoice has been generated. No payment obligation yet.
Pending	The first invoice is finalized and waiting for payment.
Trialing	The subscription is in a trial period with a processed trial invoice (zero-amount for free trials). No regular billing occurs until the trial ends.
Active	Payment authorized successfully. Renewals generate invoices automatically.
Redemption	A renewal payment failed. Solidgate retries using smart retries.
Unpaid	All payment retries exhausted. No further automatic attempts. If the outstanding invoice is paid manually, the subscription returns to ACTIVE .
Cancelled	The subscription is stopped. No further invoices are generated.
Expired	The first invoice was not paid. The subscription never activated.

Status details

Expand all

Created

CREATED is the initial state: the record exists and the first invoice has been generated. Because the invoice is finalized automatically at creation, the subscription transitions to PENDING almost immediately, staying in CREATED only briefly.

Pending

The subscription moves to PENDING when the first invoice is ready for payment. From here you collect payment. If the invoice is voided at any point, whether before or after a payment attempt, the subscription moves to EXPIRED .

Trialing

If you configure a trial period at creation, the subscription enters TRIALING after a successful trial invoice is processed (zero-amount for free trials). During the trial, no regular charges occur. You can set the trial to free or paid (a reduced amount charged at trial start). Solidgate sends the SUBSCRIPTION_TRIAL_ACTIVATED webhook event when the trial begins. When the trial ends, Solidgate generates a new invoice for the first regular billing cycle and charges the customer. Once paid, the subscription becomes ACTIVE .

Active

ACTIVE is reached when the first invoice is paid successfully. The payment instrument is saved on the subscription, the billing cycle anchor is set, and renewals begin automatically. Listen for the SUBSCRIPTION_ACTIVATED webhook event to grant access to your product.

Redemption

A renewal payment failed or was not attempted. The subscription moves to REDEMPTION and Solidgate begins retrying the payment using smart retries. Retries happen at the invoice level. The subscription itself does not change until the invoice outcome is resolved. If a retry succeeds, the invoice moves to paid and the subscription returns to ACTIVE . If all retries are exhausted, the subscription moves to either UNPAID or CANCELLED . For retry configuration, see smart retries.

Unpaid

All automatic payment retries have been exhausted. No further attempts are made. Revoke access to your product when the subscription reaches this state. You can attempt manual recovery or cancel the subscription. If the outstanding invoice is paid, the subscription returns to ACTIVE and normal billing resumes.

Cancelled

Cancelling a subscription stops all future invoice generation. You can cancel immediately or schedule cancellation for the end of the current billing period. This state is terminal: if the customer wants to resubscribe, create a new subscription. When you cancel, you can provide a free-text comment for reporting purposes. Solidgate records both the request time and the scheduled cancellation time.

Expired

A subscription expires when the first invoice is voided, whether before or after a payment attempt. The subscription never reached ACTIVE and no billing cycle started. Like cancelled, expired is terminal and the subscription cannot be reactivated.

Billing periods

The billing period determines how often Solidgate charges the customer. You set the billing period on the product price. Solidgate supports the following billing intervals:

Day: every 1 day, every 3 days
Week: every 1 week, every 2 weeks
Month: every 1 month, every 3 months
Quarter: every 3 months
Year: every 1 year

Billing cycle anchor

The billing cycle anchor ( anchor_at ) is the reference date that aligns all future billing periods. It determines the day of the month for monthly or annual intervals, and the day of the week for weekly intervals.

By default, the anchor is set to the subscription creation date. If a trial is configured, the anchor is set to the trial end date. This ensures billing dates are predictable and consistent.

When the anchor day does not exist in a given month (for example, the 31st in a 30-day month), the system uses the last day of that month. The anchor returns to the original day when the month allows it.

Trials

You can configure a trial period when creating a subscription. During the trial, the customer has access to the product under special billing terms.

Trial type	Billing during trial	Use case
Free	No charges	Product evaluation, freemium onboarding, lead generation
Paid	Single charge at trial start	Introductory pricing (for example, $1 for 7 days), low-commitment onboarding

Trial settings include the trial type (free or paid), duration, and amount (for paid trials, in minor currency units). The trial period is defined by a start and end timestamp. Free trials generate a zero-amount invoice. To validate the payment instrument, the system may perform a card verification, and the customer’s bank statement may temporarily show a small hold that is reversed automatically. Free trials can also be combined with one-time product charges on the same invoice.

When the trial ends, Solidgate generates a new invoice for the first regular billing cycle. The trial end date becomes the billing cycle anchor for all future renewals.

Line items

Each subscription contains one recurring line item that references a product price from your catalog. You can also add one-time line items, such as setup fees. One-time items added at creation appear on the activation invoice. You can add them later through subscription modification, in which case they appear on the next generated invoice.

All line items within a subscription must use the same currency. Each line item includes the product reference, price, quantity, billing type ( RECURRING or ONE_TIME ), and its current billing period.

Product and price management

Tax calculation

Tax is calculated automatically based on the customer’s address. When a subscription invoice includes address information, Solidgate recalculates the tax and returns updated totals.

Taxes

Discounts

You can apply one coupon per subscription. The discount is reflected in the invoice price breakdown after it is applied. Solidgate evaluates the discount each renewal: a one-time discount is removed after the first renewal, a limited-time discount expires after its configured duration, and a forever discount continues to apply.

Coupons

Looking for help? Contact us

Stay informed with Changelog