Subscriptions
Subscription plan and customer subscription management endpoints
List customer subscriptions
Credential: a company's API key or OAuth token.
Retrieves a paginated list of your company's customer subscriptions.
The list can be narrowed by free-text search, subscription statuses,
customerId, planId, or your own partnerReferenceId.
Pagination
Subscriptions are listed newest first. Pass each response's nextCursor
back as cursor, with the same filters, until hasMore is false.
Paging by page is deprecated, and page cannot be sent with cursor
(400 PAGINATION_CURSOR_WITH_PAGE). A cursor replayed with other filters is
refused with 400 PAGINATION_INVALID_CURSOR.
Required Scope
subscriptions-read
Required License
- Subscription — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
query Parameters
cursorOpaque cursor from the previous response's nextCursor. Returns the rows after it, in the same order. Send the same filters and sort as the request that produced it, and do not send page. The preferred way to page through a list.
pageDeprecated: page with cursor instead. Page number (1-indexed). From 2026-12-31, a page past the first of a list with more than 10,000 matching rows is refused.
limitNumber of items per page
searchSearch by customer name or subscription name
statusesFilter by subscription statuses
customerIdFilter by customer ID
planIdFilter by subscription plan ID
partnerReferenceIdFilter to the subscription(s) carrying this exact partner reconciliation reference — the clientReferenceId you passed at embedded-checkout bind time. Use it to recover a missed subscription webhook: resolve our subscription from your own order id.
List customer subscriptions › Responses
List of customer subscriptions
List of customer subscriptions
totalTotal number of customer subscriptions matching the query
limitMaximum number of items per page
nextCursorCursor for the next page; pass it as cursor. null on the last page, and on every page of a sort that cannot page by cursor — hasMore then says whether another page follows by page number.
hasMoreWhether more rows follow this page.
pageDeprecated: page with nextCursor instead. Current page number (1-indexed).
totalPagesDeprecated: page with nextCursor instead. Total number of pages available.
Assign a subscription to a customer
Credential: a company's API key or OAuth token.
Creates a customer subscription from a plan, starting on startDate.
When billingDirection is omitted, the subscription defaults to
in-advance (ADVANCE) billing.
Pass addons to create add-ons together with it: each becomes a
subscription of its own, billed on this subscription's invoice inside its
section. The response lists them under addons. addons cannot be
combined with joinBillingGroupId or formBillingGroupWithSubscriptionId
(400 SHARED_VALIDATION_FAILED, details.reason =
ADDONS_WITH_BILLING_GROUP_PLACEMENT).
The response includes the subscription's stable id — use it for all subsequent reads, updates, and cancellations; it stays valid across plan replacements and other scheduled changes.
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.
Assign a subscription to a customer › Request Body
customerIdCustomer ID to assign the subscription to
planIdSubscription plan ID
startDateStart date (ISO 8601)
endDateEnd date (ISO 8601)
billingCycleAnchorBilling cycle anchor date (ISO 8601). When the billing cycle should align to. Defaults to startDate if not provided.
prorationBehaviorHow to handle proration from startDate to billingCycleAnchor
trialDaysTrial period in days
billingDirectionBilling direction for this subscription
customerDepartmentIdCustomer department ID for invoice delivery
departmentContactOverrideIdContact override ID for department invoice delivery
Optional quantity and price overrides for products in the plan
automaticBillingWhether to enable automatic billing
allowedPaymentProvidersThe connected card provider the buyer may pay this subscription with - at most one. Empty means card payment is off. A subscription needs it before the buyer can add a first card through POST /v1/checkout/subscriptions/{id}/card-window, which otherwise answers 400 SUBSCRIPTION_MANAGE_PROVIDER_NOT_ALLOWED. It allows card payment and attaches no card: the buyer still enters the card themselves. Two providers of the same kind answer 400 INVOICE_MULTIPLE_CARD_PROVIDERS.
collectViaLeverandorserviceCollect each billing cycle via Leverandørservice (Danish direct debit) instead of a card charge. DKK-only. Requires the tenant to hold the Leverandørservice license, a configured creditor number, and a registered mandate for the customer.
joinBillingGroupIdCreate the subscription straight onto this billing group of the same customer. The group replaces billingCycleAnchor with its own billing date, and the assignment and the join commit together, so a refused join creates no subscription. startDate and prorationBehavior still decide the period up to the group's date. Cannot be combined with formBillingGroupWithSubscriptionId.
formBillingGroupWithSubscriptionIdCreate the subscription and form a NEW billing group with this existing subscription of the same customer as the lead: the lead's next billing date replaces billingCycleAnchor, and its terms are written onto the new subscription. The assignment and the formation commit together. Cannot be combined with joinBillingGroupId.
discountIdsDiscount records the subscription references, in the order they apply, by id. Each bills on every period that starts before its end: a discount that lasts a number of periods ends that many billing periods after the first one billed (after any trial), and one without a duration has no end. Each is checked when attached: it exists, a fixed or per-unit one has an amount in the subscription currency, it combines with the others, and it is not code-only. The subscription takes one use of each discount limit, however many periods it bills. Refusals: DISCOUNT_NOT_FOUND, DISCOUNT_NO_AMOUNT_IN_CURRENCY, DISCOUNT_PER_UNIT_NEEDS_LINE_SCOPE, DISCOUNT_NOT_COMBINABLE, DISCOUNT_REFERENCED_TWICE, DISCOUNT_NOT_APPLICABLE, DISCOUNT_REDEMPTION_LIMIT_REACHED, DISCOUNT_CUSTOMER_REDEMPTION_LIMIT_REACHED, DISCOUNT_DURATION_NEEDS_RECURRING_PRODUCT.
Add-ons created together with this subscription. Each becomes a subscription of its own that bills on this subscription’s invoice, inside its section, and ends when this subscription is cancelled. An add-on takes its customer, dates, billing direction and invoice details from this subscription, so it names only its plan and product overrides. The subscription and its add-ons commit together: a refused add-on creates nothing. Cannot be combined with joinBillingGroupId or formBillingGroupWithSubscriptionId (400 SHARED_VALIDATION_FAILED, details.reason = ADDONS_WITH_BILLING_GROUP_PLACEMENT). To add an add-on to an existing subscription, use POST /v1/subscriptions/{id}/addons.
discountCodeA discount code the customer gave, matched without regard to case or surrounding spaces. Its discount is attached to this subscription (not to its add-ons) and bills on every period that starts before the discount ends: a discount that lasts N periods ends N billing periods after the first one billed, which with trialDays is the first period after the trial. A code that is unknown, switched off, expired, for another customer or with no use left is refused with its DISCOUNT_* code and nothing is created. The subscription takes one use of the discount and of the code, whatever number of periods it bills.
paymentMethodIdDeprecated and non-functional. Cards are attached by the buyer with their consent (card-save link / portal checkout); any value here is rejected. Field retained only so the request is validated cleanly.
Assign a subscription to a customer › Responses
Subscription assigned to customer successfully
idCustomer subscription ID
customerIdCustomer ID
customerNameCustomer name
subscriptionNameSubscription name
startDateStart date (ISO 8601)
statusStatus of the customer subscription
currencyCurrency code (ISO 4217)
monthlyRevenueWhat the subscription bills per month today, as a decimal string, in currency, excluding VAT. Every billing interval is converted to one month: a quarter is divided by 3, half a year by 6, a year by 12, and weekly prices are multiplied by 52/12. Plan discounts, interval discounts and recurring surcharges are applied; one-off charges are not included. Add-ons are not included either: each add-on is its own subscription with its own monthlyRevenue, so adding up every subscription counts nothing twice, and the invoice a parent sends carries its own figure plus its add-ons’. Usage-based lines are left out, because their consumption is not known until the period closes: a metered line counts only through a prepaid commitment, or a fee its price charges at zero usage (see hasMeteredProducts, and GET /v1/subscriptions/{id}/usage for the usage recorded so far). A change scheduled for a later date shows from the day it takes effect. During a trial it is the price billing starts at. 0 for a subscription that has not started yet or has ended.
hasMeteredProductsWhether any product on the subscription is billed on a meter. When true, monthlyRevenue leaves the metered consumption out; read GET /v1/subscriptions/{id}/usage for the usage recorded so far in the current period.
billingDirectionBilling direction: ADVANCE bills at period start, ARREARS at period end
effectiveBillingDirectionEffective billing direction for the current period. Can differ from billingDirection if the direction was changed mid-period.
addonOfSubscriptionIdThe subscription this one is an add-on of, or null. An add-on bills on its parent’s invoice, inside the parent’s section, and ends when the parent is cancelled.
addonOfSubscriptionNameCurrent name of the subscription this one is an add-on of, or null when it is not an add-on.
The add-ons billed on this subscription’s invoice, inside its section. Empty when it has none, and always empty on an add-on — an add-on cannot have add-ons of its own.
The discount records the subscription references, in the order they apply, each as the record is now with the end date this subscription carries for it. Empty when it references none.
The products the subscription bills today, newest line first. A change scheduled for a later date is listed under GET /v1/subscriptions/{id}/scheduled-changes and appears here once it takes effect. An add-on’s products are on the add-on’s own subscription.
Entitlements currently granted by the subscription
planIdSubscription plan ID (null for ad-hoc subscriptions)
endDateEnd date (ISO 8601)
scheduledChurnDateScheduled churn date (ISO 8601). On an add-on this is its parent’s scheduled churn date: a scheduled cancellation of the parent ends every add-on with it.
trialDaysNumber of trial days granted
cancellationReasonReason provided when the subscription was cancelled
effectiveNextBillingDateThe date the NEXT invoice will be created (ISO 8601). This is an invoicing schedule marker, not a payment marker — it does not say what the customer has paid for; see paidThroughDate.
paidThroughDateThe date the subscription is paid through (ISO 8601): the first day not yet paid for. It is the end of the contiguous run of settled service periods starting at the earliest billed period, so an unpaid period caps it rather than being skipped. Null when the earliest billed period is not settled (or nothing is billed yet). Payment timing never shifts this backwards: a late payment settles exactly the period its invoice stated.
commitmentEndDateEnd date of the customer commitment period (ISO 8601)
originalStartDateOriginal start date from source system for migrated subscriptions (ISO 8601)
paymentMethodIdAssigned payment method ID
automaticBillingWhether automatic billing is enabled
allowedPaymentProvidersThe connected card provider the buyer may pay this subscription with - at most one. Empty means card payment is off. A subscription needs it before the buyer can add a first card through POST /v1/checkout/subscriptions/{id}/card-window, which otherwise answers 400 SUBSCRIPTION_MANAGE_PROVIDER_NOT_ALLOWED. It allows card payment and attaches no card: the buyer still enters the card themselves. Two providers of the same kind answer 400 INVOICE_MULTIPLE_CARD_PROVIDERS.
partnerReferenceIdYour reconciliation reference (the clientReferenceId you passed at embedded-checkout bind time), echoed back so you can match this subscription to your order. Null for any subscription not created through a partner-bound checkout.
billingGroupIdThe billing group this subscription is billed together with others on, or null when it bills on its own. A grouped subscription is billed on the group’s document and charged on the group’s card, so its own paymentMethodId is null and automaticBilling is false. A subscription that merely has other subscriptions billed as part of its own section is not grouped: it reports null and keeps its own card. So does one that IS such a section. A subscription that has joined a group but not yet reached its first shared billing date already reports the group.
Get a customer subscription by its stable id
Credential: a company's API key or OAuth token.
Returns the current state of the subscription identified by its stable id — the chain head id returned at creation. The id is resolved against the version chain, so it keeps working across plan replacements, billing-direction / cadence changes, and scheduled cancellations; the headline plan fields always reflect the version running today.
addons lists the add-ons billed on this subscription's invoice. On an
add-on, addonOfSubscriptionId names its parent, addons is empty, and
scheduledChurnDate is the parent's when the parent is scheduled to cancel.
Required Scope
subscriptions-read
Required License
- Subscription — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
path Parameters
customerSubscriptionIdThe stable subscription id (chain head id)
Get a customer subscription by its stable id › Responses
Customer subscription
idCustomer subscription ID
customerIdCustomer ID
customerNameCustomer name
subscriptionNameSubscription name
startDateStart date (ISO 8601)
statusStatus of the customer subscription
currencyCurrency code (ISO 4217)
monthlyRevenueWhat the subscription bills per month today, as a decimal string, in currency, excluding VAT. Every billing interval is converted to one month: a quarter is divided by 3, half a year by 6, a year by 12, and weekly prices are multiplied by 52/12. Plan discounts, interval discounts and recurring surcharges are applied; one-off charges are not included. Add-ons are not included either: each add-on is its own subscription with its own monthlyRevenue, so adding up every subscription counts nothing twice, and the invoice a parent sends carries its own figure plus its add-ons’. Usage-based lines are left out, because their consumption is not known until the period closes: a metered line counts only through a prepaid commitment, or a fee its price charges at zero usage (see hasMeteredProducts, and GET /v1/subscriptions/{id}/usage for the usage recorded so far). A change scheduled for a later date shows from the day it takes effect. During a trial it is the price billing starts at. 0 for a subscription that has not started yet or has ended.
hasMeteredProductsWhether any product on the subscription is billed on a meter. When true, monthlyRevenue leaves the metered consumption out; read GET /v1/subscriptions/{id}/usage for the usage recorded so far in the current period.
billingDirectionBilling direction: ADVANCE bills at period start, ARREARS at period end
effectiveBillingDirectionEffective billing direction for the current period. Can differ from billingDirection if the direction was changed mid-period.
addonOfSubscriptionIdThe subscription this one is an add-on of, or null. An add-on bills on its parent’s invoice, inside the parent’s section, and ends when the parent is cancelled.
addonOfSubscriptionNameCurrent name of the subscription this one is an add-on of, or null when it is not an add-on.
The add-ons billed on this subscription’s invoice, inside its section. Empty when it has none, and always empty on an add-on — an add-on cannot have add-ons of its own.
The discount records the subscription references, in the order they apply, each as the record is now with the end date this subscription carries for it. Empty when it references none.
The products the subscription bills today, newest line first. A change scheduled for a later date is listed under GET /v1/subscriptions/{id}/scheduled-changes and appears here once it takes effect. An add-on’s products are on the add-on’s own subscription.
Entitlements currently granted by the subscription
planIdSubscription plan ID (null for ad-hoc subscriptions)
endDateEnd date (ISO 8601)
scheduledChurnDateScheduled churn date (ISO 8601). On an add-on this is its parent’s scheduled churn date: a scheduled cancellation of the parent ends every add-on with it.
trialDaysNumber of trial days granted
cancellationReasonReason provided when the subscription was cancelled
effectiveNextBillingDateThe date the NEXT invoice will be created (ISO 8601). This is an invoicing schedule marker, not a payment marker — it does not say what the customer has paid for; see paidThroughDate.
paidThroughDateThe date the subscription is paid through (ISO 8601): the first day not yet paid for. It is the end of the contiguous run of settled service periods starting at the earliest billed period, so an unpaid period caps it rather than being skipped. Null when the earliest billed period is not settled (or nothing is billed yet). Payment timing never shifts this backwards: a late payment settles exactly the period its invoice stated.
commitmentEndDateEnd date of the customer commitment period (ISO 8601)
originalStartDateOriginal start date from source system for migrated subscriptions (ISO 8601)
paymentMethodIdAssigned payment method ID
automaticBillingWhether automatic billing is enabled
allowedPaymentProvidersThe connected card provider the buyer may pay this subscription with - at most one. Empty means card payment is off. A subscription needs it before the buyer can add a first card through POST /v1/checkout/subscriptions/{id}/card-window, which otherwise answers 400 SUBSCRIPTION_MANAGE_PROVIDER_NOT_ALLOWED. It allows card payment and attaches no card: the buyer still enters the card themselves. Two providers of the same kind answer 400 INVOICE_MULTIPLE_CARD_PROVIDERS.
partnerReferenceIdYour reconciliation reference (the clientReferenceId you passed at embedded-checkout bind time), echoed back so you can match this subscription to your order. Null for any subscription not created through a partner-bound checkout.
billingGroupIdThe billing group this subscription is billed together with others on, or null when it bills on its own. A grouped subscription is billed on the group’s document and charged on the group’s card, so its own paymentMethodId is null and automaticBilling is false. A subscription that merely has other subscriptions billed as part of its own section is not grouped: it reports null and keeps its own card. So does one that IS such a section. A subscription that has joined a group but not yet reached its first shared billing date already reports the group.
Update a customer subscription
Credential: a company's API key or OAuth token.
Update payment-related settings on an existing customer subscription.
Required Scope
subscriptions-write
Required License
- Subscription — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
path Parameters
customerSubscriptionIdThe stable subscription id (chain head id)
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Update a customer subscription › Request Body
paymentMethodIdThe card linked to the subscription. Send null to remove it. You may also echo back the card already linked (a no-op, so a full-object round-trip works), but you cannot attach or change to a different card - cards are attached by the buyer with their consent, so any value other than the currently-linked card or null is rejected with a 400.
automaticBillingWhether to automatically charge the saved card during billing
allowedPaymentProvidersThe connected card provider the buyer may pay this subscription with - at most one. Empty means card payment is off. A subscription needs it before the buyer can add a first card through POST /v1/checkout/subscriptions/{id}/card-window, which otherwise answers 400 SUBSCRIPTION_MANAGE_PROVIDER_NOT_ALLOWED. It allows card payment and attaches no card: the buyer still enters the card themselves. Two providers of the same kind answer 400 INVOICE_MULTIPLE_CARD_PROVIDERS.
Update a customer subscription › Responses
Customer subscription updated successfully
idCustomer subscription ID
customerIdCustomer ID
customerNameCustomer name
subscriptionNameSubscription name
startDateStart date (ISO 8601)
statusStatus of the customer subscription
currencyCurrency code (ISO 4217)
monthlyRevenueWhat the subscription bills per month today, as a decimal string, in currency, excluding VAT. Every billing interval is converted to one month: a quarter is divided by 3, half a year by 6, a year by 12, and weekly prices are multiplied by 52/12. Plan discounts, interval discounts and recurring surcharges are applied; one-off charges are not included. Add-ons are not included either: each add-on is its own subscription with its own monthlyRevenue, so adding up every subscription counts nothing twice, and the invoice a parent sends carries its own figure plus its add-ons’. Usage-based lines are left out, because their consumption is not known until the period closes: a metered line counts only through a prepaid commitment, or a fee its price charges at zero usage (see hasMeteredProducts, and GET /v1/subscriptions/{id}/usage for the usage recorded so far). A change scheduled for a later date shows from the day it takes effect. During a trial it is the price billing starts at. 0 for a subscription that has not started yet or has ended.
hasMeteredProductsWhether any product on the subscription is billed on a meter. When true, monthlyRevenue leaves the metered consumption out; read GET /v1/subscriptions/{id}/usage for the usage recorded so far in the current period.
billingDirectionBilling direction: ADVANCE bills at period start, ARREARS at period end
effectiveBillingDirectionEffective billing direction for the current period. Can differ from billingDirection if the direction was changed mid-period.
addonOfSubscriptionIdThe subscription this one is an add-on of, or null. An add-on bills on its parent’s invoice, inside the parent’s section, and ends when the parent is cancelled.
addonOfSubscriptionNameCurrent name of the subscription this one is an add-on of, or null when it is not an add-on.
The add-ons billed on this subscription’s invoice, inside its section. Empty when it has none, and always empty on an add-on — an add-on cannot have add-ons of its own.
The discount records the subscription references, in the order they apply, each as the record is now with the end date this subscription carries for it. Empty when it references none.
The products the subscription bills today, newest line first. A change scheduled for a later date is listed under GET /v1/subscriptions/{id}/scheduled-changes and appears here once it takes effect. An add-on’s products are on the add-on’s own subscription.
Entitlements currently granted by the subscription
planIdSubscription plan ID (null for ad-hoc subscriptions)
endDateEnd date (ISO 8601)
scheduledChurnDateScheduled churn date (ISO 8601). On an add-on this is its parent’s scheduled churn date: a scheduled cancellation of the parent ends every add-on with it.
trialDaysNumber of trial days granted
cancellationReasonReason provided when the subscription was cancelled
effectiveNextBillingDateThe date the NEXT invoice will be created (ISO 8601). This is an invoicing schedule marker, not a payment marker — it does not say what the customer has paid for; see paidThroughDate.
paidThroughDateThe date the subscription is paid through (ISO 8601): the first day not yet paid for. It is the end of the contiguous run of settled service periods starting at the earliest billed period, so an unpaid period caps it rather than being skipped. Null when the earliest billed period is not settled (or nothing is billed yet). Payment timing never shifts this backwards: a late payment settles exactly the period its invoice stated.
commitmentEndDateEnd date of the customer commitment period (ISO 8601)
originalStartDateOriginal start date from source system for migrated subscriptions (ISO 8601)
paymentMethodIdAssigned payment method ID
automaticBillingWhether automatic billing is enabled
allowedPaymentProvidersThe connected card provider the buyer may pay this subscription with - at most one. Empty means card payment is off. A subscription needs it before the buyer can add a first card through POST /v1/checkout/subscriptions/{id}/card-window, which otherwise answers 400 SUBSCRIPTION_MANAGE_PROVIDER_NOT_ALLOWED. It allows card payment and attaches no card: the buyer still enters the card themselves. Two providers of the same kind answer 400 INVOICE_MULTIPLE_CARD_PROVIDERS.
partnerReferenceIdYour reconciliation reference (the clientReferenceId you passed at embedded-checkout bind time), echoed back so you can match this subscription to your order. Null for any subscription not created through a partner-bound checkout.
billingGroupIdThe billing group this subscription is billed together with others on, or null when it bills on its own. A grouped subscription is billed on the group’s document and charged on the group’s card, so its own paymentMethodId is null and automaticBilling is false. A subscription that merely has other subscriptions billed as part of its own section is not grouped: it reports null and keeps its own card. So does one that IS such a section. A subscription that has joined a group but not yet reached its first shared billing date already reports the group.
Add an add-on to a customer subscription
Credential: a company's API key or OAuth token.
Creates an add-on of an existing subscription from a plan. The add-on is a subscription of its own — with its own stable id, returned here — that bills on the parent's invoice, inside the parent's section, from the parent's next billing date after today. Cancelling the parent cancels the add-on with it.
The parent supplies the customer, billing direction, invoice terms, recipients and payment details, so the body names only the plan, its product overrides, when the add-on starts, and how the period up to the parent's next billing date is handled. The add-on's plan must bill in the parent's currency.
An add-on cannot have add-ons of its own, so the parent must not itself be an add-on, and a parent with a scheduled cancellation takes no new add-ons. Both are refused with a coded 400 and create nothing.
Returns the new add-on; read the parent to see it listed under addons.
Required Scope
subscriptions-write
Required License
- Subscription — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
path Parameters
customerSubscriptionIdThe stable subscription id (chain head id) of the parent
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Add an add-on to a customer subscription › Request Body
planIdSubscription plan ID the add-on is created from
Optional quantity and price overrides for products in the add-on’s plan
cadenceHow often the add-on bills, as <interval>-<count> (month-1, month-3, year-1). Omit to bill at the plan’s own cadence. Any other value must be one of the plan’s alternative cadences; one the plan does not offer is refused with 400 SHARED_VALIDATION_FAILED, details.reason = ADDON_CADENCE_NOT_ON_PLAN. An add-on on a shorter cadence than its parent bills its cycles on the parent’s invoice between the parent’s own billing dates.
startDateStart date (ISO 8601) — when the customer gets the add-on. Defaults to today. The add-on bills on the parent’s invoices, on cycles that break on the parent’s billing dates walked back to this start: an add-on on the parent’s cadence that starts on one of the parent’s billing dates (today included) bills its first full period from that date.
prorationBehaviorHow to handle a partial period from startDate to the add-on’s first full cycle on the parent’s grid
Add an add-on to a customer subscription › Responses
The add-on was created
idCustomer subscription ID
customerIdCustomer ID
customerNameCustomer name
subscriptionNameSubscription name
startDateStart date (ISO 8601)
statusStatus of the customer subscription
currencyCurrency code (ISO 4217)
monthlyRevenueWhat the subscription bills per month today, as a decimal string, in currency, excluding VAT. Every billing interval is converted to one month: a quarter is divided by 3, half a year by 6, a year by 12, and weekly prices are multiplied by 52/12. Plan discounts, interval discounts and recurring surcharges are applied; one-off charges are not included. Add-ons are not included either: each add-on is its own subscription with its own monthlyRevenue, so adding up every subscription counts nothing twice, and the invoice a parent sends carries its own figure plus its add-ons’. Usage-based lines are left out, because their consumption is not known until the period closes: a metered line counts only through a prepaid commitment, or a fee its price charges at zero usage (see hasMeteredProducts, and GET /v1/subscriptions/{id}/usage for the usage recorded so far). A change scheduled for a later date shows from the day it takes effect. During a trial it is the price billing starts at. 0 for a subscription that has not started yet or has ended.
hasMeteredProductsWhether any product on the subscription is billed on a meter. When true, monthlyRevenue leaves the metered consumption out; read GET /v1/subscriptions/{id}/usage for the usage recorded so far in the current period.
billingDirectionBilling direction: ADVANCE bills at period start, ARREARS at period end
effectiveBillingDirectionEffective billing direction for the current period. Can differ from billingDirection if the direction was changed mid-period.
addonOfSubscriptionIdThe subscription this one is an add-on of, or null. An add-on bills on its parent’s invoice, inside the parent’s section, and ends when the parent is cancelled.
addonOfSubscriptionNameCurrent name of the subscription this one is an add-on of, or null when it is not an add-on.
The add-ons billed on this subscription’s invoice, inside its section. Empty when it has none, and always empty on an add-on — an add-on cannot have add-ons of its own.
The discount records the subscription references, in the order they apply, each as the record is now with the end date this subscription carries for it. Empty when it references none.
The products the subscription bills today, newest line first. A change scheduled for a later date is listed under GET /v1/subscriptions/{id}/scheduled-changes and appears here once it takes effect. An add-on’s products are on the add-on’s own subscription.
Entitlements currently granted by the subscription
planIdSubscription plan ID (null for ad-hoc subscriptions)
endDateEnd date (ISO 8601)
scheduledChurnDateScheduled churn date (ISO 8601). On an add-on this is its parent’s scheduled churn date: a scheduled cancellation of the parent ends every add-on with it.
trialDaysNumber of trial days granted
cancellationReasonReason provided when the subscription was cancelled
effectiveNextBillingDateThe date the NEXT invoice will be created (ISO 8601). This is an invoicing schedule marker, not a payment marker — it does not say what the customer has paid for; see paidThroughDate.
paidThroughDateThe date the subscription is paid through (ISO 8601): the first day not yet paid for. It is the end of the contiguous run of settled service periods starting at the earliest billed period, so an unpaid period caps it rather than being skipped. Null when the earliest billed period is not settled (or nothing is billed yet). Payment timing never shifts this backwards: a late payment settles exactly the period its invoice stated.
commitmentEndDateEnd date of the customer commitment period (ISO 8601)
originalStartDateOriginal start date from source system for migrated subscriptions (ISO 8601)
paymentMethodIdAssigned payment method ID
automaticBillingWhether automatic billing is enabled
allowedPaymentProvidersThe connected card provider the buyer may pay this subscription with - at most one. Empty means card payment is off. A subscription needs it before the buyer can add a first card through POST /v1/checkout/subscriptions/{id}/card-window, which otherwise answers 400 SUBSCRIPTION_MANAGE_PROVIDER_NOT_ALLOWED. It allows card payment and attaches no card: the buyer still enters the card themselves. Two providers of the same kind answer 400 INVOICE_MULTIPLE_CARD_PROVIDERS.
partnerReferenceIdYour reconciliation reference (the clientReferenceId you passed at embedded-checkout bind time), echoed back so you can match this subscription to your order. Null for any subscription not created through a partner-bound checkout.
billingGroupIdThe billing group this subscription is billed together with others on, or null when it bills on its own. A grouped subscription is billed on the group’s document and charged on the group’s card, so its own paymentMethodId is null and automaticBilling is false. A subscription that merely has other subscriptions billed as part of its own section is not grouped: it reports null and keeps its own card. So does one that IS such a section. A subscription that has joined a group but not yet reached its first shared billing date already reports the group.
Attach existing subscriptions as add-ons
Credential: a company's API key or OAuth token.
Turns existing subscriptions of the same customer into add-ons of this one. Each keeps its own id, plan and products, and from then on bills on this subscription's invoice, inside its section, and ends when this subscription is cancelled.
This cannot be undone. An add-on cannot be detached again; it ends only by
being cancelled. Each attached subscription loses its own saved card, because
its invoice is now this subscription's, which only this subscription's card
pays. If this subscription is billed together with others in a billing group
and the attach leaves that group billing only this one, the group's card is
removed too. cardsRemoved names every card the attach stopped charging, and
the buyer is told when a group's card comes off. Ask
POST /v1/subscriptions/{id}/addons/eligibility first to see the refusals and
the cards before committing.
An attached subscription takes this subscription's invoice terms and payment
settings, and moves onto its billing dates; one that bills on other dates is
prorated onto them. It must belong to the same customer and bill in the same
currency and direction, with the same revenue deferral and Leverandørservice
setting (SUBSCRIPTION_ADDON_PARENT_MISMATCH). A subscription that is itself
an add-on, or that has add-ons of its own, cannot be attached.
Returns this subscription, with the attached ones listed under addons.
Required Scope
subscriptions-write
Required License
- Subscription — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
path Parameters
customerSubscriptionIdThe stable subscription id (chain head id) of the parent
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Attach existing subscriptions as add-ons › Request Body
subscriptionIdsExisting subscriptions of the same customer to turn into add-ons of this one (1-19, each once). Each keeps its own id, plan and products, and from then on bills on this subscription’s invoice.
Attach existing subscriptions as add-ons › Responses
The subscriptions were attached as add-ons
idCustomer subscription ID
customerIdCustomer ID
customerNameCustomer name
subscriptionNameSubscription name
startDateStart date (ISO 8601)
statusStatus of the customer subscription
currencyCurrency code (ISO 4217)
monthlyRevenueWhat the subscription bills per month today, as a decimal string, in currency, excluding VAT. Every billing interval is converted to one month: a quarter is divided by 3, half a year by 6, a year by 12, and weekly prices are multiplied by 52/12. Plan discounts, interval discounts and recurring surcharges are applied; one-off charges are not included. Add-ons are not included either: each add-on is its own subscription with its own monthlyRevenue, so adding up every subscription counts nothing twice, and the invoice a parent sends carries its own figure plus its add-ons’. Usage-based lines are left out, because their consumption is not known until the period closes: a metered line counts only through a prepaid commitment, or a fee its price charges at zero usage (see hasMeteredProducts, and GET /v1/subscriptions/{id}/usage for the usage recorded so far). A change scheduled for a later date shows from the day it takes effect. During a trial it is the price billing starts at. 0 for a subscription that has not started yet or has ended.
hasMeteredProductsWhether any product on the subscription is billed on a meter. When true, monthlyRevenue leaves the metered consumption out; read GET /v1/subscriptions/{id}/usage for the usage recorded so far in the current period.
billingDirectionBilling direction: ADVANCE bills at period start, ARREARS at period end
effectiveBillingDirectionEffective billing direction for the current period. Can differ from billingDirection if the direction was changed mid-period.
addonOfSubscriptionIdThe subscription this one is an add-on of, or null. An add-on bills on its parent’s invoice, inside the parent’s section, and ends when the parent is cancelled.
addonOfSubscriptionNameCurrent name of the subscription this one is an add-on of, or null when it is not an add-on.
The add-ons billed on this subscription’s invoice, inside its section. Empty when it has none, and always empty on an add-on — an add-on cannot have add-ons of its own.
The discount records the subscription references, in the order they apply, each as the record is now with the end date this subscription carries for it. Empty when it references none.
The products the subscription bills today, newest line first. A change scheduled for a later date is listed under GET /v1/subscriptions/{id}/scheduled-changes and appears here once it takes effect. An add-on’s products are on the add-on’s own subscription.
The saved cards the attach stopped charging. Empty when none was.
Entitlements currently granted by the subscription
planIdSubscription plan ID (null for ad-hoc subscriptions)
endDateEnd date (ISO 8601)
scheduledChurnDateScheduled churn date (ISO 8601). On an add-on this is its parent’s scheduled churn date: a scheduled cancellation of the parent ends every add-on with it.
trialDaysNumber of trial days granted
cancellationReasonReason provided when the subscription was cancelled
effectiveNextBillingDateThe date the NEXT invoice will be created (ISO 8601). This is an invoicing schedule marker, not a payment marker — it does not say what the customer has paid for; see paidThroughDate.
paidThroughDateThe date the subscription is paid through (ISO 8601): the first day not yet paid for. It is the end of the contiguous run of settled service periods starting at the earliest billed period, so an unpaid period caps it rather than being skipped. Null when the earliest billed period is not settled (or nothing is billed yet). Payment timing never shifts this backwards: a late payment settles exactly the period its invoice stated.
commitmentEndDateEnd date of the customer commitment period (ISO 8601)
originalStartDateOriginal start date from source system for migrated subscriptions (ISO 8601)
paymentMethodIdAssigned payment method ID
automaticBillingWhether automatic billing is enabled
allowedPaymentProvidersThe connected card provider the buyer may pay this subscription with - at most one. Empty means card payment is off. A subscription needs it before the buyer can add a first card through POST /v1/checkout/subscriptions/{id}/card-window, which otherwise answers 400 SUBSCRIPTION_MANAGE_PROVIDER_NOT_ALLOWED. It allows card payment and attaches no card: the buyer still enters the card themselves. Two providers of the same kind answer 400 INVOICE_MULTIPLE_CARD_PROVIDERS.
partnerReferenceIdYour reconciliation reference (the clientReferenceId you passed at embedded-checkout bind time), echoed back so you can match this subscription to your order. Null for any subscription not created through a partner-bound checkout.
billingGroupIdThe billing group this subscription is billed together with others on, or null when it bills on its own. A grouped subscription is billed on the group’s document and charged on the group’s card, so its own paymentMethodId is null and automaticBilling is false. A subscription that merely has other subscriptions billed as part of its own section is not grouped: it reports null and keeps its own card. So does one that IS such a section. A subscription that has joined a group but not yet reached its first shared billing date already reports the group.
Check whether subscriptions can become add-ons
Credential: a company's API key or OAuth token.
Asks, without changing anything, whether this subscription can take add-ons
and whether the named existing subscriptions could be attached to it as add-ons
with POST /v1/subscriptions/{id}/addons/attach. Every refusal the attach
would answer is reported at once, where the attach itself stops at the first.
Omit subscriptionIds to ask only about this subscription.
cardsRemoved lists the saved cards the attach would stop charging: each
attached subscription's own card, since an add-on bills on its parent's invoice,
and a billing group's card when the attach would leave that group billing one
subscription. Attaching cannot be undone.
An unknown subscription 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.
path Parameters
customerSubscriptionIdThe stable subscription id (chain head id) of the parent
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Check whether subscriptions can become add-ons › Request Body
subscriptionIdsExisting subscriptions you intend to attach as add-ons (0-19, each once). Omit to ask only whether this subscription can take add-ons at all.
Check whether subscriptions can become add-ons › Responses
Whether the attach would be accepted, every refusal it would answer with, and the cards it removes
eligibleTrue when the attach would be accepted as asked
Every refusal the attach would answer, one per problem
The saved cards the attach would stop charging. Attaching cannot be undone, and a removed card is not put back: the buyer adds one again through a card flow if they want it.
Change the products on a customer subscription
Credential: a company's API key or OAuth token.
Changes the quantity, price and description of a subscription's product lines,
and adds or removes lines, from effectiveDate. The subscription keeps its id
and is not cancelled, so revenue reports measure the change as this
subscription's revenue moving up or down, not as one subscription ending and
another starting.
products lists every line the subscription has from the effective date: a
price the subscription carries today changes that line, a new price adds a
line, and a price left out of the list is removed. A field a line leaves out
keeps the value that line has on the date (its dimensions and any prepaid
usage commitment are always kept); send customPrice: null to go back to the
list price, or description: null to remove the description.
A future effectiveDate queues the change: it appears in the subscription's
scheduled changes until it takes effect, and can be cancelled there. Today or an
earlier date takes effect at once; the earliest date accepted is the day the
subscription's current terms took effect.
On a subscription billed in arrears, the invoice at the end of the period bills
each part of the period at the terms in force, by days. On one billed in
advance, prorationBehavior decides how the period the date falls inside is
settled.
The change is refused with 400 when it changes nothing
(SUBSCRIPTION_EDIT_PRODUCTS_NO_CHANGES), when it sets a quantity or a price
on a usage-metered line (SUBSCRIPTION_CANNOT_SET_QUANTITY_FOR_USAGE_BASED),
when a price is listed twice (SUBSCRIPTION_PRODUCT_ALREADY_ADDED), and when a
subscription charged to a card would fall below the smallest amount the card
can be charged (SUBSCRIPTION_CARD_BELOW_MINIMUM). A subscription that was
already below that amount keeps the change, and its automatic card payment is
switched off. A date before the current terms took effect, or after the
subscription's end date, is refused with
SUBSCRIPTION_REPLACE_PLAN_EFFECTIVE_DATE_OUT_OF_RANGE; a date on or before the
start of a period already invoiced in advance with
SUBSCRIPTION_MUTATION_SUPERSEDES_PREBILLED_PERIOD; and a subscription that is
not active, in trial, or scheduled to start with
SUBSCRIPTION_REPLACE_PLAN_REQUIRES_ACTIVE_SUBSCRIPTION.
Returns the subscription's current state.
Required Scope
subscriptions-write
Required License
- Subscription — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
path Parameters
customerSubscriptionIdThe stable subscription id (chain head id)
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Change the products on a customer subscription › Request Body
effectiveDateThe date the change takes effect (YYYY-MM-DD). A date in the future queues the change; it is listed under the subscription’s scheduled changes until then. Today or an earlier date takes effect at once; the earliest date accepted is the day the subscription’s current terms took effect.
Every product line the subscription has from the effective date. A line for a price the subscription carries today changes that line; a line for a new price adds it; a price left out of the list is removed. Each price may appear once. May be left out when the change sends discountIds or discountEndDates: the products then stay as they are.
discountIdsThe full set of discount records the subscription references from the effective date, in the order they apply. Omit to keep the ones it has; [] removes them all. A discount added is checked and takes one use of its limits; one removed gives its use back unless an invoice already applied it. The refusals are those of discountIds on POST /v1/subscriptions.
End dates for discounts the subscription references after the change, replacing the ones they have. A period that starts on or after the end date is billed without the discount; null removes the end. A discount the subscription does not reference is refused with DISCOUNT_END_DATE_NOT_REFERENCED.
prorationBehaviorHow the billing period the effective date falls inside is settled on a subscription billed in advance. The modes are described in the Proration guide. Omit for create_prorations. A subscription billed in arrears ignores it: its invoice at the end of the period bills each part of the period at the terms in force, by days.
Change the products on a customer subscription › Responses
Products changed; the subscription’s current state
idCustomer subscription ID
customerIdCustomer ID
customerNameCustomer name
subscriptionNameSubscription name
startDateStart date (ISO 8601)
statusStatus of the customer subscription
currencyCurrency code (ISO 4217)
monthlyRevenueWhat the subscription bills per month today, as a decimal string, in currency, excluding VAT. Every billing interval is converted to one month: a quarter is divided by 3, half a year by 6, a year by 12, and weekly prices are multiplied by 52/12. Plan discounts, interval discounts and recurring surcharges are applied; one-off charges are not included. Add-ons are not included either: each add-on is its own subscription with its own monthlyRevenue, so adding up every subscription counts nothing twice, and the invoice a parent sends carries its own figure plus its add-ons’. Usage-based lines are left out, because their consumption is not known until the period closes: a metered line counts only through a prepaid commitment, or a fee its price charges at zero usage (see hasMeteredProducts, and GET /v1/subscriptions/{id}/usage for the usage recorded so far). A change scheduled for a later date shows from the day it takes effect. During a trial it is the price billing starts at. 0 for a subscription that has not started yet or has ended.
hasMeteredProductsWhether any product on the subscription is billed on a meter. When true, monthlyRevenue leaves the metered consumption out; read GET /v1/subscriptions/{id}/usage for the usage recorded so far in the current period.
billingDirectionBilling direction: ADVANCE bills at period start, ARREARS at period end
effectiveBillingDirectionEffective billing direction for the current period. Can differ from billingDirection if the direction was changed mid-period.
addonOfSubscriptionIdThe subscription this one is an add-on of, or null. An add-on bills on its parent’s invoice, inside the parent’s section, and ends when the parent is cancelled.
addonOfSubscriptionNameCurrent name of the subscription this one is an add-on of, or null when it is not an add-on.
The add-ons billed on this subscription’s invoice, inside its section. Empty when it has none, and always empty on an add-on — an add-on cannot have add-ons of its own.
The discount records the subscription references, in the order they apply, each as the record is now with the end date this subscription carries for it. Empty when it references none.
The products the subscription bills today, newest line first. A change scheduled for a later date is listed under GET /v1/subscriptions/{id}/scheduled-changes and appears here once it takes effect. An add-on’s products are on the add-on’s own subscription.
Entitlements currently granted by the subscription
planIdSubscription plan ID (null for ad-hoc subscriptions)
endDateEnd date (ISO 8601)
scheduledChurnDateScheduled churn date (ISO 8601). On an add-on this is its parent’s scheduled churn date: a scheduled cancellation of the parent ends every add-on with it.
trialDaysNumber of trial days granted
cancellationReasonReason provided when the subscription was cancelled
effectiveNextBillingDateThe date the NEXT invoice will be created (ISO 8601). This is an invoicing schedule marker, not a payment marker — it does not say what the customer has paid for; see paidThroughDate.
paidThroughDateThe date the subscription is paid through (ISO 8601): the first day not yet paid for. It is the end of the contiguous run of settled service periods starting at the earliest billed period, so an unpaid period caps it rather than being skipped. Null when the earliest billed period is not settled (or nothing is billed yet). Payment timing never shifts this backwards: a late payment settles exactly the period its invoice stated.
commitmentEndDateEnd date of the customer commitment period (ISO 8601)
originalStartDateOriginal start date from source system for migrated subscriptions (ISO 8601)
paymentMethodIdAssigned payment method ID
automaticBillingWhether automatic billing is enabled
allowedPaymentProvidersThe connected card provider the buyer may pay this subscription with - at most one. Empty means card payment is off. A subscription needs it before the buyer can add a first card through POST /v1/checkout/subscriptions/{id}/card-window, which otherwise answers 400 SUBSCRIPTION_MANAGE_PROVIDER_NOT_ALLOWED. It allows card payment and attaches no card: the buyer still enters the card themselves. Two providers of the same kind answer 400 INVOICE_MULTIPLE_CARD_PROVIDERS.
partnerReferenceIdYour reconciliation reference (the clientReferenceId you passed at embedded-checkout bind time), echoed back so you can match this subscription to your order. Null for any subscription not created through a partner-bound checkout.
billingGroupIdThe billing group this subscription is billed together with others on, or null when it bills on its own. A grouped subscription is billed on the group’s document and charged on the group’s card, so its own paymentMethodId is null and automaticBilling is false. A subscription that merely has other subscriptions billed as part of its own section is not grouped: it reports null and keeps its own card. So does one that IS such a section. A subscription that has joined a group but not yet reached its first shared billing date already reports the group.
Retry a failed card payment
Credential: a company's API key or OAuth token.
Recharges the saved card for a subscription parked in awaiting_payment
after a failed charge — the API twin of the buyer portal's "Pay now".
The retry targets the outstanding unpaid card invoice; there is no request
body. It works while automatic retries are still running AND after dunning
is exhausted (it re-opens the exhausted attempt), and it ignores the
automatic ladder's backoff schedule. A cleared retry settles the invoice,
resumes the subscription, and fires the subscription.payment_succeeded
webhook.
Failure states return coded errors: PORTAL_RETRY_PAYMENT_NOT_AVAILABLE (the
subscription is not awaiting payment, has no unpaid card invoice, or has
automatic billing disabled), PORTAL_RETRY_PAYMENT_IN_PROGRESS (a concurrent
charge holds the claim, or the invoice was just paid — re-read the
subscription), and PORTAL_RETRY_PAYMENT_DECLINED (the card genuinely
declined). The codes carry the PORTAL_ prefix because this endpoint shares
its implementation with the buyer portal's own retry.
Required Scope
subscriptions-write
Required License
- Subscription — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
path Parameters
customerSubscriptionIdThe stable subscription id (chain head id)
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Retry a failed card payment › Responses
The retry charge cleared and the invoice is settled
statusAlways "succeeded" — a failed retry returns a coded error instead.
subscriptionIdThe stable subscription id the retry ran against.
invoiceIdId of the outstanding invoice the cleared charge paid.
List a subscription's pending scheduled changes
Credential: a company's API key or OAuth token.
Returns the queued, not-yet-active changes on the subscription —
future-dated plan replacements, billing-direction / cadence changes, and
scheduled cancellations. Each carries a changeId that can be cancelled
individually. Empty array when nothing is queued.
Required Scope
subscriptions-read
Required License
- Subscription — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
path Parameters
customerSubscriptionIdThe stable subscription id (chain head id)
List a subscription's pending scheduled changes › Responses
The list of pending scheduled changes
changeIdIdentifier of this queued change. Ephemeral — valid only until the change activates or is cancelled, so re-fetch rather than caching it.
kindThe kind of queued change: one of replace_plan, edit_products, change_direction, or churn.
effectiveDateThe date (YYYY-MM-DD) the change takes effect.
planIdThe plan the subscription moves to when the change activates (null for ad-hoc / non-plan changes).
subscriptionNameThe plan name the change moves to.
Cancel a single pending scheduled change
Credential: a company's API key or OAuth token.
Cancels exactly one queued change (from the scheduled-changes list) without
ending the subscription or touching its other scheduled changes. Returns
the subscription’s current state. A changeId that has already activated
or been cancelled returns 404.
Required Scope
subscriptions-write
Required License
- Subscription — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
path Parameters
customerSubscriptionIdThe stable subscription id (chain head id)
changeIdThe changeId of the scheduled change to cancel
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Cancel a single pending scheduled change › Responses
Scheduled change cancelled; the subscription’s current state
idCustomer subscription ID
customerIdCustomer ID
customerNameCustomer name
subscriptionNameSubscription name
startDateStart date (ISO 8601)
statusStatus of the customer subscription
currencyCurrency code (ISO 4217)
monthlyRevenueWhat the subscription bills per month today, as a decimal string, in currency, excluding VAT. Every billing interval is converted to one month: a quarter is divided by 3, half a year by 6, a year by 12, and weekly prices are multiplied by 52/12. Plan discounts, interval discounts and recurring surcharges are applied; one-off charges are not included. Add-ons are not included either: each add-on is its own subscription with its own monthlyRevenue, so adding up every subscription counts nothing twice, and the invoice a parent sends carries its own figure plus its add-ons’. Usage-based lines are left out, because their consumption is not known until the period closes: a metered line counts only through a prepaid commitment, or a fee its price charges at zero usage (see hasMeteredProducts, and GET /v1/subscriptions/{id}/usage for the usage recorded so far). A change scheduled for a later date shows from the day it takes effect. During a trial it is the price billing starts at. 0 for a subscription that has not started yet or has ended.
hasMeteredProductsWhether any product on the subscription is billed on a meter. When true, monthlyRevenue leaves the metered consumption out; read GET /v1/subscriptions/{id}/usage for the usage recorded so far in the current period.
billingDirectionBilling direction: ADVANCE bills at period start, ARREARS at period end
effectiveBillingDirectionEffective billing direction for the current period. Can differ from billingDirection if the direction was changed mid-period.
addonOfSubscriptionIdThe subscription this one is an add-on of, or null. An add-on bills on its parent’s invoice, inside the parent’s section, and ends when the parent is cancelled.
addonOfSubscriptionNameCurrent name of the subscription this one is an add-on of, or null when it is not an add-on.
The add-ons billed on this subscription’s invoice, inside its section. Empty when it has none, and always empty on an add-on — an add-on cannot have add-ons of its own.
The discount records the subscription references, in the order they apply, each as the record is now with the end date this subscription carries for it. Empty when it references none.
The products the subscription bills today, newest line first. A change scheduled for a later date is listed under GET /v1/subscriptions/{id}/scheduled-changes and appears here once it takes effect. An add-on’s products are on the add-on’s own subscription.
Entitlements currently granted by the subscription
planIdSubscription plan ID (null for ad-hoc subscriptions)
endDateEnd date (ISO 8601)
scheduledChurnDateScheduled churn date (ISO 8601). On an add-on this is its parent’s scheduled churn date: a scheduled cancellation of the parent ends every add-on with it.
trialDaysNumber of trial days granted
cancellationReasonReason provided when the subscription was cancelled
effectiveNextBillingDateThe date the NEXT invoice will be created (ISO 8601). This is an invoicing schedule marker, not a payment marker — it does not say what the customer has paid for; see paidThroughDate.
paidThroughDateThe date the subscription is paid through (ISO 8601): the first day not yet paid for. It is the end of the contiguous run of settled service periods starting at the earliest billed period, so an unpaid period caps it rather than being skipped. Null when the earliest billed period is not settled (or nothing is billed yet). Payment timing never shifts this backwards: a late payment settles exactly the period its invoice stated.
commitmentEndDateEnd date of the customer commitment period (ISO 8601)
originalStartDateOriginal start date from source system for migrated subscriptions (ISO 8601)
paymentMethodIdAssigned payment method ID
automaticBillingWhether automatic billing is enabled
allowedPaymentProvidersThe connected card provider the buyer may pay this subscription with - at most one. Empty means card payment is off. A subscription needs it before the buyer can add a first card through POST /v1/checkout/subscriptions/{id}/card-window, which otherwise answers 400 SUBSCRIPTION_MANAGE_PROVIDER_NOT_ALLOWED. It allows card payment and attaches no card: the buyer still enters the card themselves. Two providers of the same kind answer 400 INVOICE_MULTIPLE_CARD_PROVIDERS.
partnerReferenceIdYour reconciliation reference (the clientReferenceId you passed at embedded-checkout bind time), echoed back so you can match this subscription to your order. Null for any subscription not created through a partner-bound checkout.
billingGroupIdThe billing group this subscription is billed together with others on, or null when it bills on its own. A grouped subscription is billed on the group’s document and charged on the group’s card, so its own paymentMethodId is null and automaticBilling is false. A subscription that merely has other subscriptions billed as part of its own section is not grouped: it reports null and keeps its own card. So does one that IS such a section. A subscription that has joined a group but not yet reached its first shared billing date already reports the group.
Get a subscription's unbilled usage
Credential: a company's API key or OAuth token.
Returns the usage the subscription has recorded but not yet been invoiced
for, one entry per metered price and billing period, priced the way the
invoice will price it. Use it beside monthlyRevenue, which leaves metered
consumption out.
Usage is billed in arrears: a period's usage is invoiced when the period
closes (periodEnd). amount is what the usage recorded so far comes to,
excluding VAT and before any plan or interval discount. For a prepaid
commitment it is only the settlement above (or, with refunds, below) what was
prepaid. Usage is recorded per customer and meter, so a line flagged
quantityIsShared reports units another line also bills.
Required Scope
subscriptions-read
Required License
- Subscription — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
path Parameters
customerSubscriptionIdThe stable subscription id (chain head id)
query Parameters
asOfISO date (YYYY-MM-DD) to read the usage as of: it decides which billing period is current. Defaults to today.
Get a subscription's unbilled usage › Responses
The unbilled usage
subscriptionIdThe stable subscription id.
currencyCurrency code (ISO 4217) of every amount.
One entry per metered price and billing period that has usage not yet invoiced. A subscription behind on billing can report more than one period for a price. Empty when the subscription has no metered products.
Cancel a customer subscription
Credential: a company's API key or OAuth token.
Cancels (churns) a customer subscription according to the chosen strategy
— at the end of the current billing cycle, immediately, or on a specific
date.
effectiveDate is required when the strategy is SPECIFIC_DATE, and
refundBehavior only applies when cancelling immediately. A
non-immediate cancellation is queued and appears in the subscription's
scheduled-changes list until it takes effect.
Cancelling a subscription that has add-ons cancels its add-ons with it.
cascadedAddonSubscriptionIds names them: on an immediate cancellation,
the add-ons that ended now; on a scheduled one, the add-ons that will end
with it, as they stand when the request is made.
Returns the subscription's current state after the command is applied.
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.
Cancel a customer subscription › Request Body
idCustomer subscription ID to cancel
strategyCancellation strategy
effectiveDateEffective churn date (ISO 8601). Required when strategy is SPECIFIC_DATE.
refundBehaviorRefund behavior when canceling immediately
cancellationReasonOptional reason for cancelling the subscription
Cancel a customer subscription › Responses
Customer subscription cancelled successfully
idCustomer subscription ID
customerIdCustomer ID
customerNameCustomer name
subscriptionNameSubscription name
startDateStart date (ISO 8601)
statusStatus of the customer subscription
currencyCurrency code (ISO 4217)
monthlyRevenueWhat the subscription bills per month today, as a decimal string, in currency, excluding VAT. Every billing interval is converted to one month: a quarter is divided by 3, half a year by 6, a year by 12, and weekly prices are multiplied by 52/12. Plan discounts, interval discounts and recurring surcharges are applied; one-off charges are not included. Add-ons are not included either: each add-on is its own subscription with its own monthlyRevenue, so adding up every subscription counts nothing twice, and the invoice a parent sends carries its own figure plus its add-ons’. Usage-based lines are left out, because their consumption is not known until the period closes: a metered line counts only through a prepaid commitment, or a fee its price charges at zero usage (see hasMeteredProducts, and GET /v1/subscriptions/{id}/usage for the usage recorded so far). A change scheduled for a later date shows from the day it takes effect. During a trial it is the price billing starts at. 0 for a subscription that has not started yet or has ended.
hasMeteredProductsWhether any product on the subscription is billed on a meter. When true, monthlyRevenue leaves the metered consumption out; read GET /v1/subscriptions/{id}/usage for the usage recorded so far in the current period.
billingDirectionBilling direction: ADVANCE bills at period start, ARREARS at period end
effectiveBillingDirectionEffective billing direction for the current period. Can differ from billingDirection if the direction was changed mid-period.
addonOfSubscriptionIdThe subscription this one is an add-on of, or null. An add-on bills on its parent’s invoice, inside the parent’s section, and ends when the parent is cancelled.
addonOfSubscriptionNameCurrent name of the subscription this one is an add-on of, or null when it is not an add-on.
The add-ons billed on this subscription’s invoice, inside its section. Empty when it has none, and always empty on an add-on — an add-on cannot have add-ons of its own.
The discount records the subscription references, in the order they apply, each as the record is now with the end date this subscription carries for it. Empty when it references none.
The products the subscription bills today, newest line first. A change scheduled for a later date is listed under GET /v1/subscriptions/{id}/scheduled-changes and appears here once it takes effect. An add-on’s products are on the add-on’s own subscription.
cascadedAddonSubscriptionIdsThe add-ons cancelled together with this subscription, by their subscription ids. On an immediate cancellation these ended now; on a scheduled one they are the add-ons that will end with it, as they stand when the request is made. Empty when the subscription has no add-ons, and for clear_schedule.
Entitlements currently granted by the subscription
planIdSubscription plan ID (null for ad-hoc subscriptions)
endDateEnd date (ISO 8601)
scheduledChurnDateScheduled churn date (ISO 8601). On an add-on this is its parent’s scheduled churn date: a scheduled cancellation of the parent ends every add-on with it.
trialDaysNumber of trial days granted
cancellationReasonReason provided when the subscription was cancelled
effectiveNextBillingDateThe date the NEXT invoice will be created (ISO 8601). This is an invoicing schedule marker, not a payment marker — it does not say what the customer has paid for; see paidThroughDate.
paidThroughDateThe date the subscription is paid through (ISO 8601): the first day not yet paid for. It is the end of the contiguous run of settled service periods starting at the earliest billed period, so an unpaid period caps it rather than being skipped. Null when the earliest billed period is not settled (or nothing is billed yet). Payment timing never shifts this backwards: a late payment settles exactly the period its invoice stated.
commitmentEndDateEnd date of the customer commitment period (ISO 8601)
originalStartDateOriginal start date from source system for migrated subscriptions (ISO 8601)
paymentMethodIdAssigned payment method ID
automaticBillingWhether automatic billing is enabled
allowedPaymentProvidersThe connected card provider the buyer may pay this subscription with - at most one. Empty means card payment is off. A subscription needs it before the buyer can add a first card through POST /v1/checkout/subscriptions/{id}/card-window, which otherwise answers 400 SUBSCRIPTION_MANAGE_PROVIDER_NOT_ALLOWED. It allows card payment and attaches no card: the buyer still enters the card themselves. Two providers of the same kind answer 400 INVOICE_MULTIPLE_CARD_PROVIDERS.
partnerReferenceIdYour reconciliation reference (the clientReferenceId you passed at embedded-checkout bind time), echoed back so you can match this subscription to your order. Null for any subscription not created through a partner-bound checkout.
billingGroupIdThe billing group this subscription is billed together with others on, or null when it bills on its own. A grouped subscription is billed on the group’s document and charged on the group’s card, so its own paymentMethodId is null and automaticBilling is false. A subscription that merely has other subscriptions billed as part of its own section is not grouped: it reports null and keeps its own card. So does one that IS such a section. A subscription that has joined a group but not yet reached its first shared billing date already reports the group.
List subscription plans
Credential: a company's API key or OAuth token.
Retrieves a paginated list of your company's subscription plans.
Only active plans are returned — archived plans are excluded. Pass
?search= to filter the list by free text.
Required Scope
subscriptions-read
Required License
- Subscription — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
query Parameters
pagePage number (1-indexed)
limitNumber of items per page
searchSearch by plan name
List subscription plans › Responses
List of subscription plans
List of subscription plans
totalTotal number of subscription plans matching the query
pageCurrent page number (1-indexed)
limitMaximum number of items per page
totalPagesTotal number of pages available
Create a subscription plan
Credential: a company's API key or OAuth token.
Creates a new subscription plan (template) that can later be assigned to customers.
A plan is made up of one or more phases, and each phase lists the
products it bills via their existing priceId. Set durationValue /
durationUnit on a phase to make it time-bounded; omit them on the last
phase to leave it open-ended. When currency is omitted the company's
base currency is used, and when defaultBillingDirection is omitted the
plan defaults to in-advance (ADVANCE) billing.
The created plan is returned, including the generated plan and phase ids.
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.
Create a subscription plan › Request Body
nameSubscription plan name. Must be unique within your company.
Phases defining the plan’s billing structure. At least one phase is required.
descriptionSubscription plan description
currencyCurrency code (ISO 4217). Omit to bill in the company's own base currency.
defaultBillingDirectionDefault billing direction applied to new customer subscriptions created from this plan
Create a subscription plan › Responses
Subscription plan created successfully
idSubscription plan ID
nameSubscription plan name
isActiveWhether the subscription plan is active
currencyCurrency code (ISO 4217)
defaultBillingDirectionDefault billing direction for new customer subscriptions
Phases configured for this plan
createdAtDate the plan was created
updatedAtDate the plan was last updated
descriptionSubscription plan description
Archive a subscription plan
Credential: a company's API key or OAuth token.
Archives a subscription plan. Fails if the plan has any active or pending-cancellation customer subscriptions.
Archived plans no longer appear in the plan list.
Required Scope
subscriptions-write
Required License
- Subscription — the tenant must also hold this module license, or the request returns
403 LICENSE.REQUIRED.
path Parameters
planIdThe subscription plan ID
Headers
x-api-idempotency-keyOptional idempotency key for safely retrying mutating requests.
Archive a subscription plan › Responses
Subscription plan archived successfully