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:

Solidgate API v1 keys: for products and prices
Solidgate API v2 keys: for customers, subscriptions, and payment instruments

Hub

To generate API keys

Go to Developers.
Select the API version.
- For API v1: select the channel you need, then on the Channel details page find the API keys.
- For API v2: go to Keys, click on Create API key, name your key and optionally select a channel or multiple channels, then click on Create.
Copy your API key.

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 Solidgate API v1 .

Products

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 Solidgate API v1 .

Prices

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 Solidgate API v2 .

Customers

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.

API

Send a request to the create subscription API 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.
Change line items, the coupon, or trial terms before payment with Guide
Replace checkout line items, discounts, and trial terms on an initialized Billing checkout form using the form.updateCheckout method. form.updateCheckout. Pass at most one discount with couponId or couponCode.
The customer pays with the card form or the Guide
Add alternative payment method buttons to your payment form with customizable styling, placement, and method-specific display conditions. PayPal button. Solidgate creates the subscription, generates the activation invoice, and collects the payment. A successful PayPal payment stores a Guide
Create and manage tokenized cards and PayPal accounts linked to a Billing customer for reuse on invoices and subscription renewals. payment instrument for renewals.
Receive the response that includes the invoice ID.

Payment Form

Checkout update

APM buttons

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.

Subscription overview

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.

API

Send a request to the create webhook API 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 Webhooks API v2 reference.

Hub

To set up a webhook endpoint

Go to Developers and select the API v2 version.
Go to Webhook endpoints.
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.

Integrate invoicing

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

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.

Looking for help? Contact us

Stay informed with Changelog