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