Integrate subscriptions
Configure API access, create products and customers, set up recurring billing, handle webhook events, and manage cancellations with Solidgate
Solidgate subscriptions handle recurring billing from creation to renewal in Billing 2.0. Configure products, prices, and customers once, then create subscriptions. Set up webhook handling to track every lifecycle change.
Step 1. Get API credentials
To use the Solidgate API, you need API keys. Get your keys before proceeding with the integration:
- SolidgateAPI v1 keys: for products and prices
- SolidgateAPI v2 keys: for customers, subscriptions, and payment instruments
To generate API keys
- Go to Developers.
Select the version from the dropdown.
- For API v1: select the channel you need, then on the Channel details page find the API keys.
- For API v2: go to API keys, click on Create API keys, name your keys and optionally select a channel or multiple channels, then click on Create.
- Copy your API keys.
Step 2. Create product
A product represents what you sell. Create a product before setting up a subscription. Products are shared across Billing 1.0 and Billing 2.0. You can create and manage products in the Hub or through the SolidgateAPI v1.
Step 3. Create price
A price defines the recurring cost of a product. Create at least one recurring price before creating a subscription. The price sets the amount, currency, and billing period (for example, $9.99 per month). Prices are shared across Billing 1.0 and Billing 2.0. You can create and manage prices in the Hub or through the SolidgateAPI v1.
Step 4. Create customer
A subscription requires a customer record to identify who is being billed. A customer can be an existing record or created specifically for the subscription. You can create and manage customers in the Hub or through the SolidgateAPI v2.
Step 5. Create subscription and collect payment
Create a subscription and collect the first payment: automatically, using a saved payment instrument through the API, or when the customer submits payment through the Payment Form or Payment Link.
Send a request to the create subscriptionAPI v2 endpoint.
Pass the required customer ID, at least one recurring line item with a product_price_id and quantity, and the payment_instrument_id of a saved payment instrument to charge. Solidgate validates that the payment instrument exists, is active, and belongs to the specified customer, then queues the first charge.
The charge is not collected synchronously, so track the subscription and invoice webhook events to determine whether the first payment succeeds or fails.
Optionally, pass discounts using either coupon_id or coupon_code, trial details, description, merchant_reference, and metadata.
Checkout payment flow
Pass a checkout object when you initialize the Payment Form. Set mode to subscription, include a customer ID and at least one recurring line item referencing a product_price_id.
Also pass a merchant_reference value to identify the subscription. It must be unique within the channel and cannot be changed after creation.
Do not pass amount, currency, product_id, or invoice_id together with checkout. The Payment Form calculates the total automatically.
- Initialize the Payment Form. Solidgate previews the first charge. No subscription is created yet.
Update the checkout, if needed. Change line items, the coupon, or trial details before payment. Apply a single coupon using
checkout.discountswith eithercoupon_idorcoupon_code.- The customer pays. Solidgate creates the subscription, generates the activation invoice, and collects the payment.
- Receive the response that includes the invoice ID.
To create a subscription with the Payment Link, generate a shareable payment link with the Subscription payment type to collect the first payment without embedding a form.
Trial subscriptions
If you configure a trial period, the subscription starts in TRIALING status. For free trials, no charge is made until the trial ends. For paid trials, a single charge is collected at trial start for the trial amount.
When the trial ends, Solidgate generates a new invoice for the first regular billing cycle and charges the saved payment instrument automatically.
Handle events
To track the subscription lifecycle and get updates about its status, subscribe to subscription and invoice webhook events. Solidgate sends a SUBSCRIPTION_ACTIVATED event when the first payment completes. Listen for this event to trigger access provisioning.
Send a request to the create webhookAPI v2 endpoint with a name, URL, and the list of events you want to receive.
Pass the name to identify the endpoint, url where Solidgate should send events, and events as an array of event types to subscribe to. Optionally include channel_id to scope the endpoint to a specific channel.
For the full list of webhook management operations, see the WebhooksAPI v2 reference.
To set up a webhook endpoint
- Go to Developers, select API v2 from the dropdown.
- Go to Webhooks.
- Click on Create webhook endpoint.
- Enter a name, the endpoint URL, and select the events to subscribe to.
- Optionally, select a channel to filter events by channel.
- Save the endpoint and copy the signing secret (
wsec_...) issued for your endpoint.
Billing 2.0 uses a single signing secret per endpoint, not a public and secret key pair as in Billing 1.0 webhooks.
Subscription events
| Event | Description |
|---|---|
SUBSCRIPTION_CREATED | A subscription was created. The first invoice has been generated. |
SUBSCRIPTION_ACTIVATED | The first invoice was paid. The subscription is now active and renewals begin automatically. Primary signal for provisioning access. |
SUBSCRIPTION_TRIAL_ACTIVATED | The subscription entered a trial period. No regular billing until the trial ends. |
SUBSCRIPTION_UPDATED | The subscription was updated (for example, items, discount, or billing configuration changed). |
SUBSCRIPTION_CANCELLED | The subscription was cancelled. No further invoices are generated. |
SUBSCRIPTION_SCHEDULED_FOR_CANCELLATION | A cancellation was scheduled for a future date. The subscription remains active until the scheduled time. |
SUBSCRIPTION_EXPIRED | The first invoice was voided and the subscription expired without activating. |
Invoice events
In addition to subscription events, Solidgate sends invoice webhook events for each invoice generated by the subscription. These are useful for tracking payment outcomes at the invoice level.
Provision access to your product
When the subscription becomes active, grant your customer access to the product or service they subscribed to. Use the SUBSCRIPTION_ACTIVATED webhook event as the trigger.
On each successful renewal, Solidgate sends an INVOICE_PAID event. You can use it to extend access for the next billing period or to confirm that billing is still active.
Revoke access when you receive one of the following events:
SUBSCRIPTION_CANCELLED: the subscription was cancelled immediately.INVOICE_PAYMENT_FAILED: a renewal payment failed and the subscription moved to redemption. Depending on your business model, you may keep access during the retry window or revoke immediately.INVOICE_UNPAID: all recovery attempts for a renewal invoice are exhausted and the subscription moves toUNPAID.
Track invoice-level events, not just subscription-level events, to control access. INVOICE_PAID, INVOICE_PAYMENT_FAILED, and INVOICE_UNPAID show whether payment for a billing period was successfully collected.