Overview

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 can convert an individual customer to a business customer, but converting from business to individual is not supported.

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. If you schedule the subscription to start on a future date, it remains in the CREATED status until that date. Once active, Solidgate renews billing automatically each cycle. If a payment fails, Solidgate retries before moving the subscription to a terminal state. You can cancel the subscription at any point to stop future billing.

Create subscription

You

Create a subscription with an existing customer and at least one recurring product. 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, or pass a future starts_at value, up to one year in advance, to schedule the subscription for a later start. If scheduled, delete the subscription any time before the start date if no longer needed.

Solidgate

Creates the subscription in the CREATED status. For a subscription starting immediately, generates the first invoice automatically. For a scheduled future start, sends the SUBSCRIPTION_SCHEDULED_FOR_CREATION webhook event. The subscription is not charged until the start date arrives, when Solidgate sends SUBSCRIPTION_CREATED . If you delete the subscription before the start date, Solidgate removes it entirely and releases any coupon applied at creation.

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.

For subscriptions created through the API, Solidgate charges the payment instrument passed at creation and handles the invoice automatically.

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 includes a reference to the generated invoice. For a subscription starting immediately, it fires at creation. For a subscription scheduled for a future start, it fires on the scheduled start date instead.

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.

Retry timing and count for revenue recovery are configured in settings for 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 the invoice status setting in the Hub.

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.

Immediate cancellation is terminal. You can delete a scheduled cancellation before it takes effect. To resubscribe after cancellation, create a new subscription.

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, and discount. It also includes the merchant_reference value, the latest invoice ID, and the next_billing_at timestamp that indicates when the next renewal charge is scheduled.
To view a subscription

  1. Go to Billing > Billing 2.0 > Subscriptions.
  2. 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.

Subscription statuses

Every subscription progresses through a defined set of statuses.

Subscription status
StatusDescription
CreatedThe subscription record exists. For an immediate start, the first invoice is generated automatically. For a scheduled future start, the subscription is not charged until the start date arrives.
PendingThe first invoice is finalized and waiting for payment.
TrialingThe subscription is in a trial period with a processed trial invoice (zero-amount for free trials). No regular billing occurs until the trial ends.
ActivePayment authorized successfully. Renewals generate invoices automatically.
PausedBilling is suspended for a scheduled or indefinite period. Renewals resume when the pause ends.
RedemptionA renewal payment failed. Solidgate retries using smart retries.
UnpaidAll payment retries exhausted. No further automatic attempts. If the outstanding invoice is paid manually, the subscription returns to ACTIVE .
CancelledThe subscription is stopped. No further invoices are generated.
ExpiredThe 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 typeBilling during trialUse case
FreeNo chargesProduct evaluation, freemium onboarding, lead generation
PaidSingle charge at trial startIntroductory 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.

A free trial on its own generates a zero-amount invoice. To validate the payment instrument, the system may perform a card verification. The customer’s bank statement may temporarily show a small authorization hold, which is automatically reversed.

Both free and paid trials can include one-time product charges on the same invoice. For a paid trial, the trial amount and one-time charges are collected together in a single payment at trial start. For a free trial, the trial itself has no charge, but any one-time charges are still collected at trial start.

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 add-ons, or other non-recurring charges.

One-time items added when creating a subscription appear on the activation invoice. If the subscription includes a trial, they appear on the trial invoice instead. For a paid trial, one-time charges are collected together with the trial amount in a single payment. Items added later through subscription updates appear on the next generated invoice. After the invoice containing a one-time item is paid, the item is automatically removed from the subscription.

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

Discounts with trial options

For a paid trial, the discount applies directly to the trial charge instead of the first regular payment.

ScenarioBehavior
Once discount, paid trialApplies its full discount to the trial charge. After the trial invoice is paid, the subscription carries no discount into the first regular payment.
Limited-time or forever discount, paid trialAlso discounts the trial charge and continues to apply afterward until the discount duration ends. For a limited-time discount, the duration counts from the moment the trial charge is paid, not from the first regular payment.
Discount larger than the paid trial chargeSolidgate caps the discount at the trial amount, with no excess carried over to later payments.
Free trialWith no one-time line items on the trial invoice, there is nothing to discount. The discount applies starting with the first regular payment.

Next steps

Integrate subscriptions

Configure API access, create products and customers, and set up recurring billing.

Billing analytics

Track subscriber growth, trial conversion, and revenue trends generated by your subscriptions.


Looking for help? Contact us
Stay informed with Changelog