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
Credential: a company's API key or OAuth token.
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.
A subscription with add-ons brings them along; the response lists them under
it. The group uses one slot per subscription and add-on, at most 20
(400 SUBSCRIPTION_BILLING_GROUP_MEMBER_LIMIT with details.slotsUsed,
details.slotsRequested and details.maxSlots).
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 uses at most 20 slots: one for the lead, one for each member, and one for each add-on any of them brings along.
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, each with the add-ons it brought into the group.
Get a billing group
Credential: a company's API key or OAuth token.
Returns a billing group and the subscriptions billed together on its document,
each carrying its own next billing date, monthly revenue and add-ons — the
subscriptions whose lines bill inside its section. slotsUsed counts every
member and add-on against the maxSlots cap.
A group that has dissolved, or has only one subscription left in it, answers
with billsTogether: false and no members, as long as an invoice or credit
note names it. An id that bills nothing together and that no document names
answers 404 SUBSCRIPTION_BILLING_GROUP_NOT_FOUND, as an unknown id does.
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).
billsTogetherTrue while two or more subscriptions hold a place in the group, including one that starts billing on it later. False once the group has dissolved or only one subscription is left in it: members is then empty, the remaining subscription bills on its own invoice, and the group answers here only because an invoice or credit note names it.
billsTogetherUntilWhen the group stopped billing its subscriptions together (ISO 8601): when it dissolved, or otherwise when the last subscription to leave it left. Null while billsTogether is true. Turning a member into another member’s add-on records no date, so a group that stopped billing together that way reports the last departure before it, or null when none left.
slotsUsedThe slots the group uses: one per member and one per add-on listed under a member. This is what maxSlots caps, so adding a subscription that carries add-ons uses one slot for it and one for each add-on. Zero when billsTogether is false.
maxSlotsThe most slots a group can use, add-ons included.
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 subscriptions billed together on the group’s document, ordered by the day they start billing on the group and then by id, each with its add-ons. Holds at least two while billsTogether is true, and is empty when it is false.
dissolvedAtWhen the group dissolved (ISO 8601), or null while the group row stands. 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
Credential: a company's API key or OAuth token.
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 joiner with add-ons brings them along, and each uses a slot.
A dissolved group answers 400 SUBSCRIPTION_BILLING_GROUP_NOT_JOINABLE; form a
new group instead. An id naming fewer than two subscriptions billed together is
no group and answers 404 SUBSCRIPTION_BILLING_GROUP_NOT_FOUND.
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, each with the add-ons it brought into the group.
Remove a member from a billing group
Credential: a company's API key or OAuth token.
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 subscriptions are left billing together, the
group ends 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. An id
naming fewer than two subscriptions billed together is no group and answers
404 SUBSCRIPTION_BILLING_GROUP_NOT_FOUND.
An add-on cannot be taken off on its own
(400 SUBSCRIPTION_ADDON_CANNOT_LEAVE_ALONE, details.subscriptionId naming
it): it leaves with the member it bills under, and ends by being cancelled.
Removing a member takes its add-ons out with it. 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 subscriptions billing together, so the group ended: the remaining subscription bills on its own document from its next billing date.
Check billing group eligibility
Credential: a company's API key or OAuth token.
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.