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:

Hub To generate API keys

  1. Go to Developers.
  2. 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.
  3. 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.

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.


  1. 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 invoicePreview event.
  2. Change line items, the coupon, or trial terms before payment with form.updateCheckout. Pass at most one discount with couponId or couponCode.
  3. The customer pays with the card form, the PayPal button , Apple Pay , or Google Pay. Solidgate creates the subscription, generates the activation invoice, and collects the payment. A successful PayPal payment stores a payment instrument for renewals.
  4. 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.