Subscriptions
Subscription plan and customer subscription management endpoints
List customer subscriptions
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.
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 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
pageCurrent page number (1-indexed)
limitMaximum number of items per page
totalPagesTotal number of pages available
Assign a subscription to a customer
Creates a customer subscription from a plan, starting on startDate.
When billingDirection is omitted, the subscription defaults to
in-advance (ADVANCE) billing.
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 overrides for products in the plan
automaticBillingWhether to enable automatic billing
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.
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)
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.
Entitlements currently granted by the subscription
planIdSubscription plan ID (null for ad-hoc subscriptions)
endDateEnd date (ISO 8601)
scheduledChurnDateScheduled churn date (ISO 8601)
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
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.
Get a customer subscription by its stable id
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.
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)
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.
Entitlements currently granted by the subscription
planIdSubscription plan ID (null for ad-hoc subscriptions)
endDateEnd date (ISO 8601)
scheduledChurnDateScheduled churn date (ISO 8601)
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
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.
Update a customer subscription
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
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)
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.
Entitlements currently granted by the subscription
planIdSubscription plan ID (null for ad-hoc subscriptions)
endDateEnd date (ISO 8601)
scheduledChurnDateScheduled churn date (ISO 8601)
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
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.
Retry a failed card payment
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
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
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)
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.
Entitlements currently granted by the subscription
planIdSubscription plan ID (null for ad-hoc subscriptions)
endDateEnd date (ISO 8601)
scheduledChurnDateScheduled churn date (ISO 8601)
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
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.
Cancel a customer subscription
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.
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)
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.
Entitlements currently granted by the subscription
planIdSubscription plan ID (null for ad-hoc subscriptions)
endDateEnd date (ISO 8601)
scheduledChurnDateScheduled churn date (ISO 8601)
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
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.
List subscription plans
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
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). When omitted, defaults to the system default currency (DKK), matching the gated subscription-plan create endpoint.
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
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