FastSpring AppAPI ReferenceWebhooksJavaScript LibraryChangelogFastSpring.com
Developer Documentation
Sign In

Co-term Webhooks

Overview of co-term-related 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.

Overview

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:

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

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

  3. 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 all required co-term initiation steps (group creation, estimation, and execution) have been successfully completed, as outlined in the Prerequisites section.

Note: The customer is charged for the prorated adjustments applied during the creation of the co-term group.
subscription.group.payment.charge.completed Sent at renewal, when the system successfully processes the customer's charge (rebill) for the grouped subscription.
subscription.group.updated When a new subscription is added to an existing co-term group, the co-term group is updated to reflect the changes.
subscription.group.payment.reminder (Optional) When the payment schedule for the most recent subscription purchase is reached, a payment reminder is sent.
subscription.group.payment.charge.failed When the co-term group is unsuccessfully rebilled and enters dunning.
subscription.group.payment.overdue (Optional) When a payment becomes overdue based on the most recent purchase's schedule, an overdue notification is issued.
subscription.group.deactivated After the dunning period ends, the system initiates deactivation for each subscription belonging to the co-term group.

📘

Managing Subscriptions with Co-Terming

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.