Solidgate subscriptions handle recurring billing from creation to renewal in Billing 2.0. Configure products, prices, and customers once, then create subscriptions.
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 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 .
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 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.
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.
Read the previewed total, the discount, and the tax from the
Guide
The invoicePreview event reports the calculated invoice for a Billing checkout intent at form initialization and after a billing address change. invoicePreview event. - 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 withcouponIdorcouponCode. - The customer pays with the card form, the
Guide
Add alternative payment method buttons to your payment form with customizable styling, placement, and method-specific display conditions. PayPal button , Guide
Add an Apple Pay button to your embedded payment form for one-tap checkout with biometric authentication on supported Apple devices. Apple Pay , or Guide
Add a Google Pay button to your embedded payment form for one-tap checkout on Android devices and Chrome browsers with token security. Google Pay. Solidgate creates the subscription, generates the activation invoice, and collects the payment. A successful PayPal payment stores a Guide
View and manage saved payment methods linked to your customers to enable recurring charges without requiring customers to re-enter payment details. payment instrument for renewals. - Receive the response that includes the invoice ID.
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.
Next steps
Once the subscription is live, track its lifecycle and manage it going forward.
Handle billing events
Use webhooks to track subscription, invoice, and payment activity, respond to failed payments and disputes, and reconcile invoices with payments.
Manage subscriptions
View subscription details, update plans and quantities, cancel subscriptions, and manage the full lifecycle via API or Hub in Solidgate Billing.