Billing Groups
Several of one customer's subscriptions billing onto one shared invoice: read the set, form one, add and remove members, and ask whether a set would be accepted. Requires the Subscription license.
Form a billing group
Forms a billing group from a lead subscription and 1 to 19 other subscriptions of the same customer. The lead's next billing date becomes the day the set starts billing together, and its payment terms, invoice delivery and send offset are written onto every member. Currency, billing direction, revenue deferral and payment-method mode must already agree across the set. A member's own card is discarded: a group is charged on a card the buyer attaches to the group.
Every subscription id is the stable id GET /v1/subscriptions returns.
Required Scope
subscriptions-write
Required License
- Subscription — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Form a billing group › Request Body
leadSubscriptionIdThe subscription whose terms the group takes: its next billing date becomes the group's billing date, and its payment terms, invoice delivery and send offset are written onto every member. Not repeated in memberSubscriptionIds.
memberSubscriptionIdsThe other subscriptions of the same customer that join the group: 1 to 19, distinct, none already in a group. A group holds at most 20 members including the lead.
invoiceTemplateIdA consolidated document template for the shared invoice. Omitted or null uses the customer's, then your default.
includeMemberDetailsPdfAttach a zip with one detail document per member to each send. Defaults to false.
Form a billing group › Responses
The new group, its first shared billing date, and every member
billingGroupIdThe new group.
billingActiveFromThe day the set starts billing together (YYYY-MM-DD).
leadSubscriptionIdThe subscription whose terms the group took, echoed from the request.
Every member, the lead included.
Get a billing group
Returns a billing group with its current members, each carrying its own next
billing date and monthly revenue. A dissolved group still answers, with
dissolvedAt set and no members: the invoices it issued keep naming it.
Required Scope
subscriptions-read
Required License
- Subscription — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
path Parameters
billingGroupIdBilling group id
Get a billing group › Responses
The billing group
idBilling group id
customerIdThe one customer every member belongs to.
billingActiveFromThe day the group started, or starts, billing as a set (YYYY-MM-DD).
chargesByCardTrue when the next shared invoice is charged to the group's card rather than sent for bank payment. The card is the group's; members hold none of their own.
includeMemberDetailsPdfWhether each send also attaches a zip with one detail document per member.
The current members, ordered by the day they start billing on the group and then by id. Empty once the group has dissolved.
dissolvedAtWhen the group dissolved (ISO 8601), or null while it bills as a set. A dissolved group keeps answering here because the invoices it issued still name it.
invoiceTemplateIdThe consolidated document template the shared invoice renders from, or null to use the customer's, then your default.
Add members to a billing group
Adds 1 to 19 existing subscriptions of the group's customer to the group. The group's billing date does not move: each joiner is moved onto it, and its invoice-affecting fields are rewritten to the group's. A joiner's own card is discarded.
A dissolved group answers 400 SUBSCRIPTION_BILLING_GROUP_NOT_JOINABLE; form a
new group instead.
Required Scope
subscriptions-write
Required License
- Subscription — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
path Parameters
billingGroupIdBilling group id
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Add members to a billing group › Request Body
subscriptionIdsSubscriptions of the group's customer that join it: 1 to 19, distinct, none already in a group. The group's billing date does not move; each joiner is moved onto it.
Add members to a billing group › Responses
The group, the day the joiners start billing on it, and the joiners
billingGroupIdThe group joined.
billingActiveFromThe day the joiners start billing on the group's invoice (YYYY-MM-DD).
The subscriptions that joined.
Remove a member from a billing group
Takes one subscription off the group, effective at once. It keeps the billing
date and the fields the group gave it and bills on its own from its next
billing date. If fewer than two members remain, the whole group dissolves and
the response says so with groupDissolved: true.
The subscription must be a current member of THIS group; otherwise the request
answers 404 SUBSCRIPTION_BILLING_GROUP_MEMBER_NOT_FOUND, whose
details.groupDissolvedAt says whether the group itself has ended. While a
shared invoice is still being collected on the group's card, no member can
leave (400 SUBSCRIPTION_BILLING_GROUP_LEAVE_BLOCKED_BY_UNPAID_INVOICE).
Required Scope
subscriptions-write
Required License
- Subscription — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
path Parameters
billingGroupIdBilling group id
subscriptionIdThe subscription to remove, by its stable id
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Remove a member from a billing group › Responses
The group left, the subscription that left, and whether the group dissolved
billingGroupIdThe group the subscription left.
subscriptionIdThe subscription that left, by its stable id.
groupDissolvedTrue when this departure left fewer than two members and the whole group dissolved: the remaining member bills on its own from its next billing date.
Check billing group eligibility
Asks whether a set of subscriptions could form a billing group, or join an existing one, without writing anything. Every refusal the set carries is reported at once — at most one per subscription plus at most one about the set — where the write itself stops at the first.
mode: "form" takes leadSubscriptionId and memberSubscriptionIds;
mode: "join" takes billingGroupId and subscriptionIds. A dissolved
group answers eligible: false with a set-level refusal; an unknown group is a
404.
Required Scope
subscriptions-read
Required License
- Subscription — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Check billing group eligibility › Request Body
modeform asks whether leadSubscriptionId and memberSubscriptionIds could form a group; join asks whether subscriptionIds could join billingGroupId.
leadSubscriptionIdform: the subscription whose terms the group would take.
memberSubscriptionIdsform: the subscriptions that would join, 0 to 19. Omitted or empty asks whether the lead could lead a group at all.
billingGroupIdjoin: the group to join.
subscriptionIdsjoin: the subscriptions that would join, 1 to 19.
Check billing group eligibility › Responses
Whether the write would be accepted, and every refusal it would answer with
eligibleTrue when the write would be accepted today.
Every refusal, at most one per subscription plus at most one about the set. Empty when eligible. A subscription refused for two reasons reports the first; the second appears once the first is fixed.