Solidgate • Handle billing events

Handle billing events

Use webhooks to track subscription, invoice, and payment activity, respond to failed payments and disputes, and reconcile invoices with payments

Solidgate notifies you about billing activity through webhook events. A billing integration requires a webhook endpoint that handles these events. Most billing activity, such as subscription renewals, payment failures, retries, cancellations, and updates to customer or payment instrument records, happens on Solidgate’s side without a direct API call from you.

Set up your webhook endpoint

You can build logic to verify webhook signatures API v2 and handle Solidgate events. To start receiving notifications, you need to configure a webhook endpoint.

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 .

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

Test webhook endpoint

To test your webhook endpoint, you can:

Perform actions in a sandbox environment that trigger real events to your endpoint. For example, to trigger SUBSCRIPTION_ACTIVATED , create a subscription and complete the first payment using a test card.
Create a subscription with a short billing period to observe the full renewal cycle ( SUBSCRIPTION_RENEWED , INVOICE_PAID ) in a compressed timeline.
Use the recurring decline test card ( 4123212486997559 ) to trigger INVOICE_PAYMENT_FAILED , SUBSCRIPTION_REDEMPTION_STARTED , and eventually SUBSCRIPTION_UNPAID .

Track active subscriptions

Subscriptions require coordination between your system and Solidgate. The success or failure of a customer’s recurring payments determines whether they can continue to access your product or service.

A common pattern is to store an access expiration date for each customer and use it to determine whether their subscription is still active.

When the subscription renews, Solidgate charges the saved payment instrument and notifies your system by sending webhook events:

Receive SUBSCRIPTION_RENEWED and INVOICE_PAID .
- SUBSCRIPTION_RENEWED is a subscription-specific signal for renewals, not for one-time invoices.
- INVOICE_PAID fires for all invoices. Use billing_reason : subscription_cycle to identify renewals.
Find the customer the payment was made for on your side.
Update the customer's access expiration date to the end of the new billing period.

Use both subscription status and invoice status to determine the right access action:

Signal	Subscription status	Invoice status	Recommended action
SUBSCRIPTION_ACTIVATED	ACTIVE	PAID	Grant access.
SUBSCRIPTION_RENEWED or INVOICE_PAID	ACTIVE	PAID	Extend access to the new period.
SUBSCRIPTION_REDEMPTION_STARTED or INVOICE_DUNNING_STARTED	REDEMPTION	DUNNING	Recovery in progress. Decide whether to keep or restrict access. Solidgate does not enforce a timing rule here.
Retry succeeds	ACTIVE	PAID	Restore access if you restricted it during the retry window.
SUBSCRIPTION_UNPAID or INVOICE_UNPAID	UNPAID	UNPAID	Revoke access. The subscription no longer auto-charges but is not yet cancelled.
Retries exhausted, invoice setting is Voided	CANCELLED	VOIDED	Revoke access. The subscription is cancelled automatically.
SUBSCRIPTION_CANCELLED	CANCELLED	Not applicable	Revoke access.

Track subscription status changes

Make sure that your integration properly monitors and handles transitions between the subscription statuses described in the following table.

Some status changes require special attention:

When a subscription changes to REDEMPTION , a renewal payment has failed and Solidgate is retrying. Decide whether to keep or restrict access during this window. Listen for SUBSCRIPTION_REDEMPTION_STARTED . If the customer confirms they resolved the issue that caused the decline, collect payment at once through manual recovery instead of waiting for the next retry.
When a subscription changes to UNPAID , all automatic retries are exhausted. Revoke access and consider notifying the customer. Solidgate offers revenue recovery features that help automate this process.
When a subscription changes to CANCELLED , revoke access to your product.

Status	Description
CREATED	The subscription record exists, and the first invoice has been generated. No payment collected yet.
PENDING	The first invoice is finalized and waiting for payment.
TRIALING	The subscription is in a trial period. You can safely provision your product for the customer. The subscription transitions automatically to ACTIVE when the first regular payment is collected.
ACTIVE	The subscription is in good standing. The first invoice has been paid and renewals generate invoices automatically. For subscriptions recovering from REDEMPTION , a successful retry payment returns the subscription to ACTIVE .
REDEMPTION	A renewal payment failed. Solidgate is retrying using smart retries. Whether to keep or restrict access during this window is your decision.
UNPAID	All automatic payment retries are exhausted. No further automatic attempts. The subscription remains in place. If the outstanding invoice is paid, the subscription returns to ACTIVE . Revoke access when a subscription moves to this status.
CANCELLED	The subscription is stopped. No further invoices are generated. This is a terminal state. To resubscribe, create a new subscription.
EXPIRED	The first invoice was voided and the subscription never activated. No access was ever granted.

Subscription lifecycle

Handle payment failures

Events provide a reliable way for Solidgate to notify you of payment failures on subscription invoices. Some payment failures are temporary. For example, a card issuer might decline the initial charge but allow an automatic retry. Other payment failures are final and require action, like the customer’s payment method expiring.

Event	Description
INVOICE_PAYMENT_FAILED	A payment for an invoice failed. This event fires on every failed attempt, but only the first failure moves the subscription to REDEMPTION . If a payment fails, there are several possible actions to take: Notify the customer. Prompt the customer to update the payment instrument on the subscription. Configure smart retries to enable automatic recovery.
SUBSCRIPTION_REDEMPTION_STARTED	The recovery period has started. The subscription is in REDEMPTION and Solidgate begins retrying the charge based on your smart retries configuration. Depending on your business logic, restrict or keep access during this window. If the customer confirms they resolved the issue that caused the decline, you can collect payment through manual recovery.
SUBSCRIPTION_RENEWED or INVOICE_PAID	A retry succeeded. The subscription returns to ACTIVE . Restore access if you restricted it during redemption.
SUBSCRIPTION_UNPAID or INVOICE_UNPAID	All retries exhausted. The subscription moves to the UNPAID status. You can revoke the customer access. No further automatic charges are attempted, but you can still collect payment through manual recovery.

The outcome after retries are exhausted depends on your invoice status setting. If the invoice status setting is Voided, Solidgate cancels the subscription and sends SUBSCRIPTION_CANCELLED instead of SUBSCRIPTION_UNPAID .

Revenue recovery

Handle disputes and chargebacks

Solidgate monitors subscriptions for fraud signals, disputes, and chargebacks. When one of these signals arrives, Solidgate can cancel the affected subscription automatically, independent of the dunning flow. You do not need to trace a dispute back to the subscription yourself.

Event	Description
SUBSCRIPTION_CANCELLED	Sent when Solidgate cancels a subscription in response to a dispute, chargeback, or fraud signal. The cancellation_info.reason field identifies the trigger. Solidgate Hub , you can set up the alert-based cancellation flow for subscription in the Billing settings.

Alert-based cancellation

Match invoices to payments

Each invoice payment has its own identifier, separate from the payment that processed the charge. Use the invoice_payment object’s payment_id field to link the invoice back to that payment.

Event	Description
INVOICE_PAID	The payment_id field identifies the payment that successfully charged the invoice.
INVOICE_PAYMENT_FAILED	The payment_id field identifies the payment attempt that failed.

To match invoice payments in bulk, generate the INVOICE_PAYMENTS report API v2 .

Webhook event reference

Solidgate triggers events every time a subscription or invoice changes state. Some events are sent immediately when a subscription is created, while others are sent on regular billing periods.

Make sure that your integration properly the events listed below. For example, you might want to notify a customer when a payment fails, restrict access when the subscription enters redemption, or revoke access when a subscription is cancelled.

Subscription events

Event	Description	Recommended action
SUBSCRIPTION_CREATED	Sent when a subscription is created. The first invoice has been generated. The subscription status is CREATED .	Use this event to create or sync the subscription record in your system.
SUBSCRIPTION_ACTIVATED	Sent when the first invoice is paid. The subscription moves to ACTIVE and renewals begin automatically.	Use this event to provision access to your product.
SUBSCRIPTION_TRIAL_ACTIVATED	Sent when the subscription enters a trial period. No regular billing occurs until the trial ends.	Use this event to grant the customer trial access to your product.
SUBSCRIPTION_UPDATED	Sent when a subscription is changed. For example, updating items, applying a discount, or changing billing configuration all trigger this event.	Use this event to sync the updated subscription details in your system.
SUBSCRIPTION_RENEWED	Sent when a subscription is renewed. The invoice for the next billing period was paid and the subscription continues. Fires alongside INVOICE_PAID for the same renewal, but unlike INVOICE_PAID , only fires for subscription renewals, not one-time invoices.	Use this event to extend access to the new billing period.
SUBSCRIPTION_REDEMPTION_STARTED	Sent when a renewal payment fails and the recovery period begins. The subscription moves to REDEMPTION . Fires at the same moment as the INVOICE_DUNNING_STARTED event.	Depending on your business logic, restrict access or start re-engagement with the customer at this point. You can collect payment through manual recovery if the customer confirms they resolved the issue that caused the decline.
SUBSCRIPTION_UNPAID	Sent when all retry attempts for a renewal invoice are exhausted and payment was not collected. The subscription moves to UNPAID .	Revoke access to your product. The subscription remains in place but no further automatic charges are attempted, though you can still collect payment through manual recovery.
SUBSCRIPTION_SCHEDULED_FOR_CANCELLATION	Sent when a cancellation is scheduled for a future date. The subscription remains ACTIVE and continues billing until the scheduled date.	Use this event to trigger a retention flow or notify the customer before access ends.
SUBSCRIPTION_CANCELLED	Sent when a subscription is cancelled. No further invoices are generated.	Revoke access to your product.
SUBSCRIPTION_EXPIRED	Sent when the first invoice is voided and the subscription expires without ever activating. The customer never had access.	No action needed.

Subscriptions

Invoice events

Because invoices can be created for both subscriptions and one-time purchases, invoice events fire independently of subscription events. For subscription billing, the most important invoice events are:

Event	Description	Recommended action
INVOICE_CREATED	Sent when an invoice is generated for a subscription billing period or a one-time purchase.	Use this event to record the upcoming charge or display it to the customer before payment is collected.
INVOICE_PAID	Sent when the invoice is successfully paid. Every successful charge, whether the first payment or a renewal, fires this event. The payload includes the billing_reason field, which identifies why the invoice was created.	Use this event to provision access when the subscription activates or to extend access on renewal.
INVOICE_PAYMENT_FAILED	A payment attempt for the invoice failed.	If a payment fails, there are several possible actions to take: Notify the customer. Prompt the customer to update the payment instrument on the subscription. Configure your smart retries settings to enable automatic recovery.
INVOICE_DUNNING_STARTED	Sent when the invoice enters the retry window. Fires at the same moment as the SUBSCRIPTION_REDEMPTION_STARTED event. Both events are raised when the subscription moves to REDEMPTION status.	The same action applies as for the SUBSCRIPTION_REDEMPTION_STARTED event. Restrict access or start re-engagement with the customer.
INVOICE_UNPAID	Sent when all retry attempts are exhausted and the invoice remains unpaid. The subscription moves to UNPAID .	Revoke access to your product.

Expand all

All invoice events

Event	Description
INVOICE_CREATED	An invoice was created. Invoice created Webhook
INVOICE_UPDATED	An invoice was modified. Invoice updated Webhook
INVOICE_FINALIZED	An invoice moved from draft to open. Invoice finalized Webhook
INVOICE_PAID	Payment was authorized and the purchase can be activated. Invoice paid Webhook
INVOICE_PAYMENT_FAILED	A payment attempt was declined. Invoice payment failed Webhook
INVOICE_DUNNING_STARTED	Dunning started. Invoice dunning started Webhook
INVOICE_UNPAID	The invoice was unpaid. Invoice unpaid Webhook
INVOICE_PAYMENT_REFUNDED	A refund was issued. Invoice payment refunded Webhook
INVOICE_VOIDED	The invoice was canceled or expired. Invoice voided Webhook
INVOICE_DELETED	The invoice was deleted. Invoice deleted Webhook
INVOICE_FINALIZATION_FAILED	Finalization was rejected due to missing required data. Invoice finalization failed Webhook

Invoicing

Customer events

Solidgate sends customer events when a customer record is created or updated. Since subscriptions and invoices rely on customer records for billing and tax information, these events help keep your local database in sync.

Event	Description	Recommended action
CUSTOMER_CREATED	Sent when a new customer record is successfully created.	Use this event to create or sync the customer record in your system.
CUSTOMER_UPDATED	Sent when a customer record is updated, for example, if the email, address, or tax information changes.	Use this event to keep the customer record updated in your system.

Customers

Payment instrument events

Solidgate sends payment instrument events when a saved payment method (like a credit card) is added, removed, or expires.

Event	Description	Recommended action
PAYMENT_INSTRUMENT_CREATED	Sent when a new payment instrument is saved to a customer. This usually happens when the first invoice of a subscription is paid and the payment method is vaulted for future renewals.	Use this event to store the payment instrument reference for display in your customer's billing settings.
PAYMENT_INSTRUMENT_REVOKED	Sent when a payment instrument is removed or invalidated. If this was the default payment method for an active subscription, renewals fail unless a new instrument is provided.	Prompt the customer to add a new payment method to avoid a failed renewal.
PAYMENT_INSTRUMENT_EXPIRED	Sent when a saved payment instrument reaches its expiration date.	Prompt the customer to update their payment details before the next subscription renewal to prevent payment failure.

Payment instruments

Looking for help? Contact us

Stay informed with Changelog