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
- 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 Solidgate API 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 Solidgate API 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 Solidgate API v2 .
Step 5. Create subscription
You can collect the first payment through the Payment Form with subscription parameters, or by using a Payment Link. Either method creates the subscription record and collects the first payment in a single step. Include a customer ID and at least one recurring line item referencing a product price.
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.
Via 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. Via Hub 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.
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.