Subscriptions

Download schema

Subscription plan and customer subscription management endpoints

List customer subscriptions

GET

https://api.ledgerbee.com/api

/v1/subscriptions

x-api-key (header)

OAuth 2.0

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

List customer subscriptions › query Parameters

page

number · min: 1

Page number (1-indexed)

Example: 1

Default: 1

limit

number · min: 1 · max: 100

Number of items per page

Example: 25

Default: 25

search

string

Search by customer name or subscription name

statuses

string[]

Filter by subscription statuses

Enum values:

scheduled

trial

awaiting_payment

active

pending_cancellation

paused

cancelled

expired

customerId

string

Filter by customer ID

planId

string

Filter by subscription plan ID

partnerReferenceId

string

Filter 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.

Example: order_7f3a9c21

List customer subscriptions › Responses

List of customer subscriptions

PublicListCustomerSubscriptionsResponse

PublicCustomerSubscriptionListItem[] · required

List of customer subscriptions

total

number · required

Total number of customer subscriptions matching the query

Example: 42

page

number · required

Current page number (1-indexed)

Example: 1

limit

number · required

Maximum number of items per page

Example: 25

totalPages

number · required

Total number of pages available

Example: 2

Assign a subscription to a customer

POST

https://api.ledgerbee.com/api

/v1/subscriptions

x-api-key (header)

OAuth 2.0

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

Assign a subscription to a customer › Request Body

PublicAssignSubscriptionRequest

customerId

string · required

Customer ID to assign the subscription to

Example: 550e8400-e29b-41d4-a716-446655440000

planId

string · required

Subscription plan ID

Example: 550e8400-e29b-41d4-a716-446655440000

startDate

string · required

Start date (ISO 8601)

Example: 2024-01-01

endDate

string

End date (ISO 8601)

Example: 2025-01-01

billingCycleAnchor

string

Billing cycle anchor date (ISO 8601). When the billing cycle should align to. Defaults to startDate if not provided.

Example: 2024-02-01

prorationBehavior

string · enum

How to handle proration from startDate to billingCycleAnchor

Enum values:

create_prorations

always_invoice

none

Example: none

Default: none

trialDays

number · min: 0 · max: 365

Trial period in days

Example: 14

billingDirection

string · enum

Billing direction for this subscription

Enum values:

advance

arrears

Example: advance

customerDepartmentId

string

Customer department ID for invoice delivery

Example: 550e8400-e29b-41d4-a716-446655440000

departmentContactOverrideId

string

Contact override ID for department invoice delivery

Example: 550e8400-e29b-41d4-a716-446655440000

PublicAssignSubscriptionProductOverride[]

Optional quantity overrides for products in the plan

paymentMethodId

string

Payment method ID to assign for automatic billing

Example: 550e8400-e29b-41d4-a716-446655440000

automaticBilling

boolean

Whether to enable automatic billing

Example: false

Assign a subscription to a customer › Responses

Subscription assigned to customer successfully

PublicCustomerSubscriptionResponse

id

string · required

Customer subscription ID

Example: 550e8400-e29b-41d4-a716-446655440000

customerId

string · required

Customer ID

Example: 550e8400-e29b-41d4-a716-446655440000

customerName

string · required

Customer name

Example: Acme Corporation

subscriptionName

string · required

Subscription name

Example: Premium Plan

startDate

string · required

Start date (ISO 8601)

Example: 2024-01-01

status

string · enum · required

Status of the customer subscription

Enum values:

scheduled

trial

awaiting_payment

active

pending_cancellation

paused

cancelled

expired

Example: active

currency

string · required

Currency code (ISO 4217)

Example: DKK

billingDirection

string · enum · required

Billing direction: ADVANCE bills at period start, ARREARS at period end

Enum values:

advance

arrears

Example: advance

effectiveBillingDirection

string · enum · required

Effective billing direction for the current period. Can differ from billingDirection if the direction was changed mid-period.

Enum values:

advance

arrears

Example: advance

planId

string

Subscription plan ID (null for ad-hoc subscriptions)

Example: 550e8400-e29b-41d4-a716-446655440000

endDate

string

End date (ISO 8601)

Example: 2025-01-01

scheduledChurnDate

string

Scheduled churn date (ISO 8601)

Example: 2024-07-15

trialDays

number

Number of trial days granted

Example: 14

cancellationReason

string

Reason provided when the subscription was cancelled

Example: Customer requested downgrade

effectiveNextBillingDate

string

Effective next billing date (ISO 8601)

Example: 2024-02-01

commitmentEndDate

string

End date of the customer commitment period (ISO 8601)

Example: 2025-12-31

originalStartDate

string

Original start date from source system for migrated subscriptions (ISO 8601)

Example: 2023-01-01

paymentMethodId

string | null

Assigned payment method ID

Example: 550e8400-e29b-41d4-a716-446655440000

automaticBilling

boolean

Whether automatic billing is enabled

Example: true

partnerReferenceId

string | null

Your 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.

Example: order_7f3a9c21

POST/v1/subscriptions

curl https://api.ledgerbee.com/api/v1/subscriptions \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "planId": "550e8400-e29b-41d4-a716-446655440000",
  "startDate": "2024-01-01",
  "endDate": "2025-01-01",
  "billingCycleAnchor": "2024-02-01",
  "prorationBehavior": "none",
  "trialDays": 14,
  "billingDirection": "advance",
  "customerDepartmentId": "550e8400-e29b-41d4-a716-446655440000",
  "departmentContactOverrideId": "550e8400-e29b-41d4-a716-446655440000",
  "productOverrides": [
    {
      "priceId": "550e8400-e29b-41d4-a716-446655440000",
      "quantity": 25
    }
  ],
  "paymentMethodId": "550e8400-e29b-41d4-a716-446655440000",
  "automaticBilling": false
}'

Example Request Body

{
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "planId": "550e8400-e29b-41d4-a716-446655440000",
  "startDate": "2024-01-01",
  "endDate": "2025-01-01",
  "billingCycleAnchor": "2024-02-01",
  "prorationBehavior": "none",
  "trialDays": 14,
  "billingDirection": "advance",
  "customerDepartmentId": "550e8400-e29b-41d4-a716-446655440000",
  "departmentContactOverrideId": "550e8400-e29b-41d4-a716-446655440000",
  "productOverrides": [
    {
      "priceId": "550e8400-e29b-41d4-a716-446655440000",
      "quantity": 25
    }
  ],
  "paymentMethodId": "550e8400-e29b-41d4-a716-446655440000",
  "automaticBilling": false
}

json

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "customerName": "Acme Corporation",
  "planId": "550e8400-e29b-41d4-a716-446655440000",
  "subscriptionName": "Premium Plan",
  "startDate": "2024-01-01",
  "endDate": "2025-01-01",
  "scheduledChurnDate": "2024-07-15",
  "status": "active",
  "currency": "DKK",
  "trialDays": 14,
  "cancellationReason": "Customer requested downgrade",
  "billingDirection": "advance",
  "effectiveBillingDirection": "advance",
  "effectiveNextBillingDate": "2024-02-01",
  "commitmentEndDate": "2025-12-31",
  "originalStartDate": "2023-01-01",
  "paymentMethodId": "550e8400-e29b-41d4-a716-446655440000",
  "automaticBilling": true,
  "partnerReferenceId": "order_7f3a9c21"
}

json

application/json

Get a customer subscription by its stable id

GET

https://api.ledgerbee.com/api

/v1/subscriptions/{customerSubscriptionId}

x-api-key (header)

OAuth 2.0

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

Get a customer subscription by its stable id › path Parameters

customerSubscriptionId

string · required

The stable subscription id (chain head id)

Get a customer subscription by its stable id › Responses

Customer subscription

PublicCustomerSubscriptionResponse

id

string · required

Customer subscription ID

Example: 550e8400-e29b-41d4-a716-446655440000

customerId

string · required

Customer ID

Example: 550e8400-e29b-41d4-a716-446655440000

customerName

string · required

Customer name

Example: Acme Corporation

subscriptionName

string · required

Subscription name

Example: Premium Plan

startDate

string · required

Start date (ISO 8601)

Example: 2024-01-01

status

string · enum · required

Status of the customer subscription

Enum values:

scheduled

trial

awaiting_payment

active

pending_cancellation

paused

cancelled

expired

Example: active

currency

string · required

Currency code (ISO 4217)

Example: DKK

billingDirection

string · enum · required

Billing direction: ADVANCE bills at period start, ARREARS at period end

Enum values:

advance

arrears

Example: advance

effectiveBillingDirection

string · enum · required

Effective billing direction for the current period. Can differ from billingDirection if the direction was changed mid-period.

Enum values:

advance

arrears

Example: advance

planId

string

Subscription plan ID (null for ad-hoc subscriptions)

Example: 550e8400-e29b-41d4-a716-446655440000

endDate

string

End date (ISO 8601)

Example: 2025-01-01

scheduledChurnDate

string

Scheduled churn date (ISO 8601)

Example: 2024-07-15

trialDays

number

Number of trial days granted

Example: 14

cancellationReason

string

Reason provided when the subscription was cancelled

Example: Customer requested downgrade

effectiveNextBillingDate

string

Effective next billing date (ISO 8601)

Example: 2024-02-01

commitmentEndDate

string

End date of the customer commitment period (ISO 8601)

Example: 2025-12-31

originalStartDate

string

Original start date from source system for migrated subscriptions (ISO 8601)

Example: 2023-01-01

paymentMethodId

string | null

Assigned payment method ID

Example: 550e8400-e29b-41d4-a716-446655440000

automaticBilling

boolean

Whether automatic billing is enabled

Example: true

partnerReferenceId

string | null

Example: order_7f3a9c21

GET/v1/subscriptions/{customerSubscriptionId}

curl https://api.ledgerbee.com/api/v1/subscriptions/:customerSubscriptionId \
  --header 'x-api-key: <api-key>'

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "customerName": "Acme Corporation",
  "planId": "550e8400-e29b-41d4-a716-446655440000",
  "subscriptionName": "Premium Plan",
  "startDate": "2024-01-01",
  "endDate": "2025-01-01",
  "scheduledChurnDate": "2024-07-15",
  "status": "active",
  "currency": "DKK",
  "trialDays": 14,
  "cancellationReason": "Customer requested downgrade",
  "billingDirection": "advance",
  "effectiveBillingDirection": "advance",
  "effectiveNextBillingDate": "2024-02-01",
  "commitmentEndDate": "2025-12-31",
  "originalStartDate": "2023-01-01",
  "paymentMethodId": "550e8400-e29b-41d4-a716-446655440000",
  "automaticBilling": true,
  "partnerReferenceId": "order_7f3a9c21"
}

json

application/json

Update a customer subscription

PATCH

https://api.ledgerbee.com/api

/v1/subscriptions/{customerSubscriptionId}

x-api-key (header)

OAuth 2.0

Update payment-related settings on an existing customer subscription.

Required Scope

subscriptions-write

Update a customer subscription › path Parameters

customerSubscriptionId

string · required

The stable subscription id (chain head id)

Update a customer subscription › Request Body

PublicUpdateSubscriptionRequest

paymentMethodId

string | null

Payment method ID to assign. Set to null to clear.

Example: 550e8400-e29b-41d4-a716-446655440000

automaticBilling

boolean

Whether to automatically charge the saved card during billing

Example: true

Update a customer subscription › Responses

Customer subscription updated successfully

PublicCustomerSubscriptionResponse

id

string · required

Customer subscription ID

Example: 550e8400-e29b-41d4-a716-446655440000

customerId

string · required

Customer ID

Example: 550e8400-e29b-41d4-a716-446655440000

customerName

string · required

Customer name

Example: Acme Corporation

subscriptionName

string · required

Subscription name

Example: Premium Plan

startDate

string · required

Start date (ISO 8601)

Example: 2024-01-01

status

string · enum · required

Status of the customer subscription

Enum values:

scheduled

trial

awaiting_payment

active

pending_cancellation

paused

cancelled

expired

Example: active

currency

string · required

Currency code (ISO 4217)

Example: DKK

billingDirection

string · enum · required

Billing direction: ADVANCE bills at period start, ARREARS at period end

Enum values:

advance

arrears

Example: advance

effectiveBillingDirection

string · enum · required

Effective billing direction for the current period. Can differ from billingDirection if the direction was changed mid-period.

Enum values:

advance

arrears

Example: advance

planId

string

Subscription plan ID (null for ad-hoc subscriptions)

Example: 550e8400-e29b-41d4-a716-446655440000

endDate

string

End date (ISO 8601)

Example: 2025-01-01

scheduledChurnDate

string

Scheduled churn date (ISO 8601)

Example: 2024-07-15

trialDays

number

Number of trial days granted

Example: 14

cancellationReason

string

Reason provided when the subscription was cancelled

Example: Customer requested downgrade

effectiveNextBillingDate

string

Effective next billing date (ISO 8601)

Example: 2024-02-01

commitmentEndDate

string

End date of the customer commitment period (ISO 8601)

Example: 2025-12-31

originalStartDate

string

Original start date from source system for migrated subscriptions (ISO 8601)

Example: 2023-01-01

paymentMethodId

string | null

Assigned payment method ID

Example: 550e8400-e29b-41d4-a716-446655440000

automaticBilling

boolean

Whether automatic billing is enabled

Example: true

partnerReferenceId

string | null

Example: order_7f3a9c21

PATCH/v1/subscriptions/{customerSubscriptionId}

curl https://api.ledgerbee.com/api/v1/subscriptions/:customerSubscriptionId \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "paymentMethodId": "550e8400-e29b-41d4-a716-446655440000",
  "automaticBilling": true
}'

Example Request Body

{
  "paymentMethodId": "550e8400-e29b-41d4-a716-446655440000",
  "automaticBilling": true
}

json

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "customerName": "Acme Corporation",
  "planId": "550e8400-e29b-41d4-a716-446655440000",
  "subscriptionName": "Premium Plan",
  "startDate": "2024-01-01",
  "endDate": "2025-01-01",
  "scheduledChurnDate": "2024-07-15",
  "status": "active",
  "currency": "DKK",
  "trialDays": 14,
  "cancellationReason": "Customer requested downgrade",
  "billingDirection": "advance",
  "effectiveBillingDirection": "advance",
  "effectiveNextBillingDate": "2024-02-01",
  "commitmentEndDate": "2025-12-31",
  "originalStartDate": "2023-01-01",
  "paymentMethodId": "550e8400-e29b-41d4-a716-446655440000",
  "automaticBilling": true,
  "partnerReferenceId": "order_7f3a9c21"
}

json

application/json

List a subscription’s pending scheduled changes

GET

https://api.ledgerbee.com/api

/v1/subscriptions/{customerSubscriptionId}/scheduled-changes

x-api-key (header)

OAuth 2.0

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

List a subscription’s pending scheduled changes › path Parameters

customerSubscriptionId

string · required

The stable subscription id (chain head id)

List a subscription’s pending scheduled changes › Responses

The list of pending scheduled changes

PublicScheduledChange

changeId

string · required

Identifier of this queued change. Ephemeral — valid only until the change activates or is cancelled, so re-fetch rather than caching it.

Example: 550e8400-e29b-41d4-a716-446655440000

kind

string · required

The kind of queued change: one of replace_plan, edit_products, change_direction, or churn.

Example: replace_plan

effectiveDate

string · required

The date (YYYY-MM-DD) the change takes effect.

Example: 2024-07-01

planId

string | null · required

The plan the subscription moves to when the change activates (null for ad-hoc / non-plan changes).

Example: 550e8400-e29b-41d4-a716-446655440000

subscriptionName

string · required

The plan name the change moves to.

Example: Pro (annual)

Cancel a single pending scheduled change

DELETE

https://api.ledgerbee.com/api

/v1/subscriptions/{customerSubscriptionId}/scheduled-changes/{changeId}

x-api-key (header)

OAuth 2.0

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

Cancel a single pending scheduled change › path Parameters

customerSubscriptionId

string · required

The stable subscription id (chain head id)

changeId

string · required

The changeId of the scheduled change to cancel

Cancel a single pending scheduled change › Responses

Scheduled change cancelled; the subscription’s current state

PublicCustomerSubscriptionResponse

id

string · required

Customer subscription ID

Example: 550e8400-e29b-41d4-a716-446655440000

customerId

string · required

Customer ID

Example: 550e8400-e29b-41d4-a716-446655440000

customerName

string · required

Customer name

Example: Acme Corporation

subscriptionName

string · required

Subscription name

Example: Premium Plan

startDate

string · required

Start date (ISO 8601)

Example: 2024-01-01

status

string · enum · required

Status of the customer subscription

Enum values:

scheduled

trial

awaiting_payment

active

pending_cancellation

paused

cancelled

expired

Example: active

currency

string · required

Currency code (ISO 4217)

Example: DKK

billingDirection

string · enum · required

Billing direction: ADVANCE bills at period start, ARREARS at period end

Enum values:

advance

arrears

Example: advance

effectiveBillingDirection

string · enum · required

Effective billing direction for the current period. Can differ from billingDirection if the direction was changed mid-period.

Enum values:

advance

arrears

Example: advance

planId

string

Subscription plan ID (null for ad-hoc subscriptions)

Example: 550e8400-e29b-41d4-a716-446655440000

endDate

string

End date (ISO 8601)

Example: 2025-01-01

scheduledChurnDate

string

Scheduled churn date (ISO 8601)

Example: 2024-07-15

trialDays

number

Number of trial days granted

Example: 14

cancellationReason

string

Reason provided when the subscription was cancelled

Example: Customer requested downgrade

effectiveNextBillingDate

string

Effective next billing date (ISO 8601)

Example: 2024-02-01

commitmentEndDate

string

End date of the customer commitment period (ISO 8601)

Example: 2025-12-31

originalStartDate

string

Original start date from source system for migrated subscriptions (ISO 8601)

Example: 2023-01-01

paymentMethodId

string | null

Assigned payment method ID

Example: 550e8400-e29b-41d4-a716-446655440000

automaticBilling

boolean

Whether automatic billing is enabled

Example: true

partnerReferenceId

string | null

Example: order_7f3a9c21

DELETE/v1/subscriptions/{customerSubscriptionId}/scheduled-changes/{changeId}

curl https://api.ledgerbee.com/api/v1/subscriptions/:customerSubscriptionId/scheduled-changes/:changeId \
  --request DELETE \
  --header 'x-api-key: <api-key>'

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "customerName": "Acme Corporation",
  "planId": "550e8400-e29b-41d4-a716-446655440000",
  "subscriptionName": "Premium Plan",
  "startDate": "2024-01-01",
  "endDate": "2025-01-01",
  "scheduledChurnDate": "2024-07-15",
  "status": "active",
  "currency": "DKK",
  "trialDays": 14,
  "cancellationReason": "Customer requested downgrade",
  "billingDirection": "advance",
  "effectiveBillingDirection": "advance",
  "effectiveNextBillingDate": "2024-02-01",
  "commitmentEndDate": "2025-12-31",
  "originalStartDate": "2023-01-01",
  "paymentMethodId": "550e8400-e29b-41d4-a716-446655440000",
  "automaticBilling": true,
  "partnerReferenceId": "order_7f3a9c21"
}

json

application/json

Cancel a customer subscription

POST

https://api.ledgerbee.com/api

/v1/subscriptions/cancel

x-api-key (header)

OAuth 2.0

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

Cancel a customer subscription › Request Body

PublicCancelSubscriptionRequest

id

string · required

Customer subscription ID to cancel

Example: 550e8400-e29b-41d4-a716-446655440000

strategy

string · enum · required

Cancellation strategy

Enum values:

immediately

end_of_cycle

specific_date

clear_schedule

Example: end_of_cycle

effectiveDate

string

Effective churn date (ISO 8601). Required when strategy is SPECIFIC_DATE.

Example: 2024-06-30

refundBehavior

string · enum

Refund behavior when canceling immediately

Enum values:

none

last_invoice

prorated

Example: none

Default: none

cancellationReason

string

Optional reason for cancelling the subscription

Example: Customer requested downgrade

Cancel a customer subscription › Responses

Customer subscription cancelled successfully

PublicCustomerSubscriptionResponse

id

string · required

Customer subscription ID

Example: 550e8400-e29b-41d4-a716-446655440000

customerId

string · required

Customer ID

Example: 550e8400-e29b-41d4-a716-446655440000

customerName

string · required

Customer name

Example: Acme Corporation

subscriptionName

string · required

Subscription name

Example: Premium Plan

startDate

string · required

Start date (ISO 8601)

Example: 2024-01-01

status

string · enum · required

Status of the customer subscription

Enum values:

scheduled

trial

awaiting_payment

active

pending_cancellation

paused

cancelled

expired

Example: active

currency

string · required

Currency code (ISO 4217)

Example: DKK

billingDirection

string · enum · required

Billing direction: ADVANCE bills at period start, ARREARS at period end

Enum values:

advance

arrears

Example: advance

effectiveBillingDirection

string · enum · required

Effective billing direction for the current period. Can differ from billingDirection if the direction was changed mid-period.

Enum values:

advance

arrears

Example: advance

planId

string

Subscription plan ID (null for ad-hoc subscriptions)

Example: 550e8400-e29b-41d4-a716-446655440000

endDate

string

End date (ISO 8601)

Example: 2025-01-01

scheduledChurnDate

string

Scheduled churn date (ISO 8601)

Example: 2024-07-15

trialDays

number

Number of trial days granted

Example: 14

cancellationReason

string

Reason provided when the subscription was cancelled

Example: Customer requested downgrade

effectiveNextBillingDate

string

Effective next billing date (ISO 8601)

Example: 2024-02-01

commitmentEndDate

string

End date of the customer commitment period (ISO 8601)

Example: 2025-12-31

originalStartDate

string

Original start date from source system for migrated subscriptions (ISO 8601)

Example: 2023-01-01

paymentMethodId

string | null

Assigned payment method ID

Example: 550e8400-e29b-41d4-a716-446655440000

automaticBilling

boolean

Whether automatic billing is enabled

Example: true

partnerReferenceId

string | null

Example: order_7f3a9c21

POST/v1/subscriptions/cancel

curl https://api.ledgerbee.com/api/v1/subscriptions/cancel \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "strategy": "end_of_cycle",
  "effectiveDate": "2024-06-30",
  "refundBehavior": "none",
  "cancellationReason": "Customer requested downgrade"
}'

Example Request Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "strategy": "end_of_cycle",
  "effectiveDate": "2024-06-30",
  "refundBehavior": "none",
  "cancellationReason": "Customer requested downgrade"
}

json

Example Responses

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "customerName": "Acme Corporation",
  "planId": "550e8400-e29b-41d4-a716-446655440000",
  "subscriptionName": "Premium Plan",
  "startDate": "2024-01-01",
  "endDate": "2025-01-01",
  "scheduledChurnDate": "2024-07-15",
  "status": "active",
  "currency": "DKK",
  "trialDays": 14,
  "cancellationReason": "Customer requested downgrade",
  "billingDirection": "advance",
  "effectiveBillingDirection": "advance",
  "effectiveNextBillingDate": "2024-02-01",
  "commitmentEndDate": "2025-12-31",
  "originalStartDate": "2023-01-01",
  "paymentMethodId": "550e8400-e29b-41d4-a716-446655440000",
  "automaticBilling": true,
  "partnerReferenceId": "order_7f3a9c21"
}

json

application/json

List subscription plans

GET

https://api.ledgerbee.com/api

/v1/subscriptions/plans

x-api-key (header)

OAuth 2.0

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

List subscription plans › query Parameters

page

number · min: 1

Page number (1-indexed)

Example: 1

Default: 1

limit

number · min: 1 · max: 100

Number of items per page

Example: 25

Default: 25

search

string

Search by plan name

List subscription plans › Responses

List of subscription plans

PublicListSubscriptionPlansResponse

PublicSubscriptionPlanResponse[] · required

List of subscription plans

total

number · required

Total number of subscription plans matching the query

Example: 42

page

number · required

Current page number (1-indexed)

Example: 1

limit

number · required

Maximum number of items per page

Example: 25

totalPages

number · required

Total number of pages available

Example: 2

GET/v1/subscriptions/plans

curl https://api.ledgerbee.com/api/v1/subscriptions/plans \
  --header 'x-api-key: <api-key>'

Example Responses

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Premium Plan",
      "description": "Our premium subscription plan with all features",
      "isActive": true,
      "currency": "DKK",
      "defaultBillingDirection": "advance",
      "phases": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "sequence": 1,
          "name": "Intro promo",
          "discountType": "percentage",
          "discountValue": "10.00",
          "durationValue": 3,
          "durationUnit": "month",
          "products": [
            {
              "priceId": "550e8400-e29b-41d4-a716-446655440000",
              "quantity": 1,
              "customPrice": "89.99"
            }
          ]
        }
      ],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 25,
  "totalPages": 2
}

json

application/json

Archive a subscription plan

POST

https://api.ledgerbee.com/api

/v1/subscriptions/plans/archive/{planId}

x-api-key (header)

OAuth 2.0

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

Archive a subscription plan › path Parameters

planId

string · required

The subscription plan ID

Archive a subscription plan › Responses

Subscription plan archived successfully

No data returned

Projects VAT Codes