Create a new co-term group

This endpoint lets you create a new co-term group by grouping subscriptions that share the same criteria.

The subscriptions you want to group together must share the same interval, currency, payment method, and account ID. If the subscriptions do not meet these criteria, FastSpring returns an error.

Co-Term Group Statuses

This table lists the four possible statuses for a cotermed group:

Status	Description
`CREATED`	Status for a newly created co-term group.
`ESTIMATED`	Status after the `POST` `/estimate` method is called.
`EXECUTED`	Status after the `POST` `/execute` method is called.
`UNGROUPED`	Indicates that the coterm group was deleted.

Working with `displayName`

When you create a co-term group, you can optionally provide a displayName in the request body for better identification. If you don't include displayName FastSpring will be generate one based on the grouping criteria .

Only one group with the same criteria combination is allowed. Attempting to create another group with the same criteria will result in a bad request.

Use Case: Create a Co-Term Group

This request creates a co-term group with a specified display name and a list of subscription IDs:

{
    "accountId": "V9dCaXJiQhmlQLKFe3sIYQ", // The unique identifier for the account.
    "coTermGroup": {
        "displayName": "some_display_name", // The optional display name for the co-term group.
        "subscriptions": [
            "0gK9THIwSmuK9Ij16UbhGw",
            "jOFqVINuSnaTRu3dpOih2Q",
            "jOFqVINuSnaTRu3dsadspOih2Q"
        ]
    }
}

{
    "action": "subscriptions.coterm.create",
    "accountId": "V9dCaXJiQhmlQLKFe3sIYQ",
    "result": "success",
    "coTermGroup": {
        "cotermGroupId": "3hMll2pFRDSpEDfEIauxRA", // The unique identifier of the co-term group.
        "displayName": "some_display_name", // The optional name of the co-term group.
        "groupingCriteria": [
            {
                "interval": [
                    {
                        "unit": "MONTH",
                        "unitCount": 1
                    }
                ],
                "currency": [
                    "EUR"
                ],
                "paymentMethod": [
                    {
                        "type": "card",
                        "ending": "*4242 (EUR)"
                    }
                ]
            }
        ],
        "subscriptions": [
            {
                "subscription": "0gK9THIwSmuK9Ij16UbhGw", // Subscription ID.
                "status": "CO_TERMED" // Status after the update.
            },
            {
                "subscription": "jOFqVINuSnaTRu3dpOih2Q",
                "status": "CO_TERMED"
            },
            {
                "subscription": "jOFqVINuSnaTRu3dsadspOih2Q",
                "status": "NOT_ELIGIBLE", // Indicates why the subscription isn't eligible for coterming.
                "error": {
                    "code": "subscription",
                    "message": "Subscription id: 'jOFqVINuSnaTRu3dsadspOih2Q' does not exist" // Error message.
                }
            }
        ]
    }
}

Partial Success Response

This response shows a partial success, where some subscriptions are eligible for co-terming while others aren't:

{
    "action": "subscriptions.coterm.create",
    "account": "V9dCaXJiQhmlQLKFe3sIYQ",
    "error": {
        "code": "subscription list validation",
        "message": "Minimum number eligible subscriptions should be at least 2" // Error indicating not enough eligible subscriptions.
    },
    "subscription": [
        {
            "subscription": "0gK9THIwSmuK9Ij16UbhGw",
            "status": "READY_FOR_CO_TERMING" // Status indicating the subscription is ready.
        },
        {
            "subscription": "jOFqVINuSnaTRu3dpOih2Q",
            "status": "NOT_ELIGIBLE",
            "error": {
                "code": "subscription",
                "message": "Subscription is part of an existing co-term group with id: 'R2nyrlQ4RYS71UfAq9lyUA'. Please remove the subscription from that group before adding to a new co-term group." // Error indicating subscription conflict
            }
        },
        {
            "subscription": "jOFqVINuSnaTRu3dsadspOih2Q",
            "status": "NOT_ELIGIBLE",
            "error": {
                "code": "subscription",
                "message": "Subscription id: 'jOFqVINuSnaTRu3dsadspOih2Q' does not exist" // Error indicating subscription not found.
            }
        }
    ]
}

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.

Co-Term Group Statuses

Working with displayName

Use Case: Create a Co-Term Group

Partial Success Response

Error handling

Working with `displayName`