Overview of co-term webhooks.
Limited Feature Availability:We currently offer the co-term webhooks feature in beta for early testing and feedback. It is not yet generally available and is currently accessible only to a limited group of users.
Co-term webhooks notify your system of events across the subscription group lifecycle and billing process. They provide data on actions such as co-term group creation, proration adjustments, billing charge completions, and co-term group deactivation.
By monitoring these webhooks, your system can automate billing operations, update records, trigger notifications, and manage dunning workflows in real-time.
Prerequisites
Before you can receive co-term-related webhook events, you have to initiate the co-term webhooks. To initiate co-term webhooks, follow the steps below:
-
Create a co-term group:
POST /subscriptions/coterm
Start by grouping the relevant subscriptions together using the create a new co-term group API endpoint.
-
Generate a co-term group estimate:
POST /subscriptions/coterm/`{cotermGroupId}`/estimate
Calculate any proration or adjustments for the grouped subscriptions using the generate a co-term group estimate API endpoint. This step provides an estimate of the changes that will be applied.
-
Execute the co-term group:
POST /subscriptions/coterm/`{cotermGroupId}`/execute
Finalize the process by calling the execute a co-term group API endpoint. This step performs the following actions:
-
The system applies the calculated adjustments.
-
The following webhook events are triggered simultaneously:
subscription.group.created
subscription.group.prorated
-
The system updates the renewal date for the co-term group.
-
The customer is charged the prorated amount.
-
Co-term webhook events
The table below provides an overview of all co-term webhook events and their trigger conditions:
Event Name | Trigger Condition |
---|---|
subscription.group.created / subscription.group.prorated | Triggered after co-term initiation steps are completed (group creation, estimation, and execution). The customer is charged for prorated adjustments. |
subscription.group.payment.charge.completed | Sent at renewal when the charge (rebill) succeeds for the grouped subscription. |
subscription.group.updated | Sent when a new subscription is added to an existing co-term group. |
subscription.group.payment.reminder | (Optional) Sent at the scheduled reminder time for the most recent purchase. |
subscription.group.payment.charge.failed | Sent when the grouped rebill fails and the co-term group enters dunning. |
subscription.group.payment.overdue | (Optional) Sent when a payment becomes overdue based on the purchase schedule. |
subscription.group.deactivated | Sent after the dunning period ends, when subscriptions in the co-term group are deactivated. |
Tip:Check out our Managing Subscriptions with Co-Terming recipe for a step-by-step guide to retrieving, creating, estimating, executing, and managing co-term groups for subscriptions using FastSpring’s API.