Retrieve active, auto-renewing subscriptions

This endpoint retrieves active, auto-renewing subscriptions, grouped by billing interval, currency, and payment type.

It doesn't include subscriptions that are in trial, paused, scheduled for deactivation or cancellation, termed subscriptions with a fixed number of billing periods, or those that renew into another product.

Example Use Cases

This section contains sample requests that address a number of co-terming use cases.

Get Eligible Subscriptions For a Given `account_id`

This request retrieves subscriptions for a given account, organized by co-term groups (if any) and potential new subscription groups based on billing interval, currency, and payment method.

curl --request GET \
     --url https://api.fastspring.com/subscriptions/coterm/account/0OFELKg7R4OY6w3zpH5o3Q \
     --header 'accept: application/json'

{
    "action": "subscriptions.coterm.get",
    "account": "0OFELKg7R4OY6w3zpH5o3Q",
    "result": "success",
    "coTermGroups": [
        { // The first is a group of monthly subscriptions in USD.
          // The group is associated with a Visa ending in *1142.
            "groupingCriteria": {
                "interval": [
                    {
                        "unit": "month",
                        "length": 1
                    }
                ],
                "currency": [
                    "USD"
                ],
                "paymentMethodType": [
                    {
                        "type": "visa",
                        "ending": "*1142"
                    }
                ]
            },
            "subscriptions": [
                {
                    "subscription": "vktINapBTMuppTTAjFkL7w",
                    "baseSubscriptionProduct": "basic",
                    "baseSubscriptionProductDisplay": "Basic",
                    "periodStartDate": 1711584000000,
                    "periodStartDateDisplay": "3/28/24",
                    "periodStartDateDisplayISO8601": "2024-03-28",
                    "nextPeriodDate": 1714262400000,
                    "nextPeriodDateDisplay": "4/28/24",
                    "nextPeriodDateDisplayISO8601": "2024-04-28",
                    "coTermStatus": "Ready for Co-Terming",
                    "renewalAmount": "$11.12"
                },
                {
                    "subscription": "7b1a5PxqQkCy_oG18TF43A",
                    "baseSubscriptionProduct": "pro",
                    "baseSubscriptionProductDisplay": "Pro",
                    "periodStartDate": 1711584000000,
                    "periodStartDateDisplay": "3/28/24",
                    "periodStartDateDisplayISO8601": "2024-03-28",
                    "nextPeriodDate": 1714262400000,
                    "nextPeriodDateDisplay": "4/28/24",
                    "nextPeriodDateDisplayISO8601": "2024-04-28",
                    "coTermStatus": "Ready for Co-Terming",
                    "renewalAmount": "$23.15"
                },
                {
                    "subscription": "5P_iG8USQRuLvneREeuJPQ",
                    "baseSubscriptionProduct": "starter",
                    "baseSubscriptionProductDisplay": "Starter",
                    "periodStartDate": 1711584000000,
                    "periodStartDateDisplay": "3/28/24",
                    "periodStartDateDisplayISO8601": "2024-03-28",
                    "nextPeriodDate": 1714262400000,
                    "nextPeriodDateDisplay": "4/28/24",
                    "nextPeriodDateDisplayISO8601": "2024-04-28",
                    "coTermStatus": "Ready for Co-Terming",
                    "renewalAmount": "$16.25"
                }
            ]
        },
        { // The second is a group of monthly subscriptions in USD. 
          // The group is associated with a Visa ending in *0007.
            "groupingCriteria": {
                "interval": [
                    {
                        "unit": "month",
                        "length": 1
                    }
                ],
                "currency": [
                    "USD"
                ],
                "paymentMethodType": [
                    {
                        "type": "visa",
                        "ending": "*0007"
                    }
                ]
            },
            "subscriptions": [
                {
                    "subscription": "_K9FcPihTbqpERKlqfVU8Q",
                    "baseSubscriptionProduct": "enterprise",
                    "baseSubscriptionProductDisplay": "Enterprise",
                    "periodStartDate": 1711584000000,
                    "periodStartDateDisplay": "3/28/24",
                    "periodStartDateDisplayISO8601": "2024-03-28",
                    "nextPeriodDate": 1714262400000,
                    "nextPeriodDateDisplay": "4/28/24",
                    "nextPeriodDateDisplayISO8601": "2024-04-28",
                    "coTermStatus": "Ready for Co-Terming",
                    "renewalAmount": "$110.92"
                }
            ]
        },
        { // The last is a group of monthly subscriptions in USD.
          // The group is associated with a card ending in *4242.
            "groupingCriteria": {
                "interval": [
                    {
                        "unit": "month",
                        "length": 1
                    }
                ],
                "currency": [
                    "USD"
                ],
                "paymentMethodType": [
                    {
                        "type": "card",
                        "ending": "*4242"
                    }
                ]
            },
            "subscriptions": [
                {
                    "subscription": "3RbDqGHVQGqnJxF5kYzbgg",
                    "baseSubscriptionProduct": "pro",
                    "baseSubscriptionProductDisplay": "Pro",
                    "periodStartDate": 1706659200000,
                    "periodStartDateDisplay": "1/31/24",
                    "periodStartDateDisplayISO8601": "2024-01-31",
                    "nextPeriodDate": 1709164800000,
                    "nextPeriodDateDisplay": "2/29/24",
                    "nextPeriodDateDisplayISO8601": "2024-02-29",
                    "coTermStatus": "Ready for Co-Terming",
                    "renewalAmount": "$16.15"
                },
                {
                    "subscription": "VLTWKPEjQBy8BeagPDmBpw",
                    "baseSubscriptionProduct": "standard",
                    "baseSubscriptionProductDisplay": "Standard",
                    "periodStartDate": 1706659200000,
                    "periodStartDateDisplay": "1/31/24",
                    "periodStartDateDisplayISO8601": "2024-01-31",
                    "nextPeriodDate": 1710288000000,
                    "nextPeriodDateDisplay": "3/13/24",
                    "nextPeriodDateDisplayISO8601": "2024-03-13",
                    "coTermStatus": "Ready for Co-Terming",
                    "renewalAmount": "$8.50"
                },
                {
                    "subscription": "gLj0yYuITrOFuUDLUbETDA",
                    "baseSubscriptionProduct": "starter",
                    "baseSubscriptionProductDisplay": "Starter",
                    "periodStartDate": 1706659200000,
                    "periodStartDateDisplay": "1/31/24",
                    "periodStartDateDisplayISO8601": "2024-01-31",
                    "nextPeriodDate": 1709164800000,
                    "nextPeriodDateDisplay": "2/29/24",
                    "nextPeriodDateDisplayISO8601": "2024-02-29",
                    "coTermStatus": "Ready for Co-Terming",
                    "renewalAmount": "$4.25"
                },
                {
                    "subscription": "ixn7rbAHRASeSEHLKFRugw",
                    "baseSubscriptionProduct": "enterprise",
                    "baseSubscriptionProductDisplay": "Enterprise",
                    "periodStartDate": 1706659200000,
                    "periodStartDateDisplay": "1/31/24",
                    "periodStartDateDisplayISO8601": "2024-01-31",
                    "nextPeriodDate": 1709164800000,
                    "nextPeriodDateDisplay": "2/29/24",
                    "nextPeriodDateDisplayISO8601": "2024-02-29",
                    "coTermStatus": "Ready for Co-Terming",
                    "renewalAmount": "$85.00"
                },
                {
                    "subscription": "1b5ZmI1nTLKt3Add3r-r4Q",
                    "baseSubscriptionProduct": "standard",
                    "baseSubscriptionProductDisplay": "Standard",
                    "periodStartDate": 1704844800000,
                    "periodStartDateDisplay": "1/10/24",
                    "periodStartDateDisplayISO8601": "2024-01-10",
                    "nextPeriodDate": 1708387200000,
                    "nextPeriodDateDisplay": "2/20/24",
                    "nextPeriodDateDisplayISO8601": "2024-02-20",
                    "coTermStatus": "Ready for Co-Terming",
                    "renewalAmount": "$7.22"
                }
            ]
        }
    ]
}

Get Co-Termed Subscriptions by Interval, Currency, Payment Method, and Status

This request retrieves co-term subscription groups filtered by an 8-week interval, using EUR as the currency, the Discover payment method, and a status of CO_TERMED.

curl --request GET \
     --url 'https://api.fastspring.com/subscriptions/coterm/account/0OFELKg7R4OY6w3zpH5o3Q?interval=W8&currency=EUR&paymentmethodtype=discover&status=CO_TERMED' \
     --header 'accept: application/json'

{
    "action": "subscriptions.coterm.get",
    "account": "0OFELKg7R4OY6w3zpH5o3Q",  // The unique account identifier.
    "result": "success",
    "coTermGroups": [
        {
            "groupingCriteria": {
                "interval": [
                    {
                        "unit": "week",  // Interval unit based on interval=W8.
                        "length": 8  
                    }
                ],
                "currency": [
                    "EUR"  // Currency based on currency=EUR.
                ],
                "paymentMethodType": [
                    {
                        "type": "discover",  // Payment method type based on paymentmethodtype=discover.
                        "ending": "*5678"
                    }
                ]
            },
            "subscriptions": [
                {
                    "subscription": "z7G9PqQkCy_oG12WTFQ56A",
                    "baseSubscriptionProduct": "premium",
                    "baseSubscriptionProductDisplay": "Premium",
                    "periodStartDate": 1711584000000,
                    "periodStartDateDisplay": "3/28/24",
                    "periodStartDateDisplayISO8601": "2024-03-28",
                    "nextPeriodDate": 1714262400000,
                    "nextPeriodDateDisplay": "4/28/24",
                    "nextPeriodDateDisplayISO8601": "2024-04-28",
                    "coTermStatus": "Co-Termed",  // Indicates that the subscription is co-termed.
                    "renewalAmount": "€45.67"
                },
                {
                    "subscription": "7d1b5PxqQkCy_oG18TF43A",
                    "baseSubscriptionProduct": "pro",
                    "baseSubscriptionProductDisplay": "Pro",
                    "periodStartDate": 1711584000000,
                    "periodStartDateDisplay": "3/28/24",
                    "periodStartDateDisplayISO8601": "2024-03-28",
                    "nextPeriodDate": 1714262400000,
                    "nextPeriodDateDisplay": "4/28/24",
                    "nextPeriodDateDisplayISO8601": "2024-04-28",
                    "coTermStatus": "Co-Termed",  // Indicates that the subscription is co-termed.
                    "renewalAmount": "€29.15"
                }
            ]
        }
    ]
}

Query Parameter Values

The two tables in this section explain the potential values for the status and interval query parameters.

`status` Parameter Values

This table explains the possible values for the status query parameter.

Code	Type	Description
`READY_FOR_CO_TERMING`	string	The subscription is eligible for grouping with other subscriptions for synchronized renewals.
`CO_TERMED`	string	The subscription is a member of a co-term group with a common renewal date.
`NOT_ELIGIBLE`	string	The subscription is not eligible for co-terming.
`OPT_OUT`	string	A subscription where the customer once opted out of co-terming at least once or was previously removed from a co-term group.

`interval` Parameter Values

This table lists the possible values for the interval query parameter. You can use these values to specify billing intervals for subscriptions. Each code corresponds to a specific duration.

Unit	Code	Equivalent Duration
Days	`D90`	90 Days
Weeks	`W`	1 Week
	`BW`	2 Weeks
	`F`	4 Weeks
	`W8`	8 Weeks
	`W12`	12 Weeks
Months	`M`	1 Month
	`M2`	2 Months
Quarters	`Q`	3 Months
Years	`BY`	6 Months
	`Y`	1 Year
	`Y2`	2 Years
	`Y3`	3 Years

Error handling

This table lists errors you may run into when working with this endpoint, as well as solutions to help you troubleshoot.

Status Code	Error Message	Solution
`400`	`AccountId is not present in the request`	Ensure the `accountId` is included in your request payload.
`400`	`Account not found with id: [account_id]`	Verify the `accountId` is correct.
`400`	`Number of subscriptions cannot exceed the maximum of [max_allowed] allowed`	Reduce the number of subscriptions in the request to be within the allowed limit.
`400`	`Minimum number eligible subscriptions should be at least 2`	Ensure that at least two eligible subscriptions are included in the request.
`422`	`Subscription ID [subscription_id] is not valid to co-term`	Verify the subscription ID is correct and eligible for co-terming.
`422`	`Subscription is part of an existing co-term group with id: [coterm_group_id]`	Remove the subscription from the existing co-term group before adding it to a new one.
`422`	`Subscription Id: [subscription_id] does not have same Account with id: [account_id]`	Ensure all subscriptions in the request belong to the same account.
`422`	`All subscriptions must have same grouping criteria (interval, currency, and payment method type)`	Verify that all subscriptions have matching grouping criteria, including interval, currency, and payment method type.
`500`	`Error retrieving subscription co-term information`	Retry the request or contact FastSpring support if the issue persists.
`500`	`Error handling co-term request`	Retry the request or contact FastSpring support if the issue persists.