Get all subscriptions

GET

subscriptions

curl -X GET \
 /subscriptions \
 --header "Authorization: Bearer <token>"

{
  "data": [
    {
      "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "externalId": "<string>",
      "paymentMethod": {
        "id": "<string>",
        "gatewayName": "wallet",
        "type": "sepa_debit",
        "default": true,
        "status": "active",
        "enabled": true,
        "name": "<string>",
        "creationDate": "2023-11-07T05:31:56Z",
        "expirationDate": "2023-11-07T05:31:56Z",
        "card": {
          "brand": "Visa",
          "last4": "4242",
          "expMonth": 12,
          "expYear": 2022,
          "cardHolder": "Max Mustermann"
        },
        "sepaDebit": {
          "iban": "DE8937*********3232",
          "bic": "COBADEFFXXX",
          "mandateReference": "MNDT-2021-123456",
          "signingDate": "2021-01-01T00:00:00+00:00"
        },
        "paypal": {
          "email": "max@mustermann.de",
          "billingAgreementId": "I-1J5gqz2eZvKYlo2C2X2X2X2X"
        }
      },
      "invoiceAddress": {
        "id": "<string>",
        "vatId": "DE123456789",
        "type": "TYPE_DEFAULT",
        "default": "true",
        "status": "active",
        "city": "Berlin",
        "zip": "12345",
        "street": "Musterstraße",
        "houseNumber": "1a",
        "countryCode": "DE",
        "companyName": "ACME Inc.",
        "salutation": "Herr",
        "addition": "c/o John Doe",
        "costCentre": "123456789",
        "firstName": "John",
        "lastName": "Doe"
      },
      "number": "S-00000001",
      "customer": {
        "id": "00000000-0000-0000-0000-000000000000",
        "customerNumber": "CUSTOMER-000",
        "timeZone": "Europe/Berlin",
        "firstName": "John",
        "lastName": "Doe",
        "currencyCode": "EUR",
        "companyName": "Acme Inc.",
        "datevId": "123456789",
        "status": "STATUS_ACTIVE"
      },
      "plan": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "family": {
          "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
          "createdAt": "2021-01-01T00:00:00+00:00",
          "updatedAt": "2021-01-01T00:00:00+00:00"
        },
        "code": "basic-m2023",
        "originProduct": {
          "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
          "name": "Basic",
          "description": "For small teams.",
          "internalName": "Basic (Weekly)",
          "type": "product",
          "measurement": {
            "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
            "unit": {
              "id": {},
              "name": "Stück",
              "createdAt": "2021-01-01T00:00:00+00:00",
              "updatedAt": "2021-01-01T00:00:00+00:00"
            },
            "code": "users",
            "description": "The number of users.",
            "aggregationType": "<any>",
            "fairBilling": true,
            "type": "<any>"
          },
          "invoiceVisibility": "always",
          "costCentre": {},
          "taxGroup": {},
          "customFields": {
            "field1": "value1",
            "field2": "value2"
          }
        },
        "allowCheckout": true,
        "status": "<any>",
        "changeBehaviour": "upgradeable_and_downgradeable",
        "changeApplyBehaviour": "end_of_period",
        "createdAt": "2023-11-07T05:31:56Z",
        "name": "<string>",
        "description": "<string>"
      },
      "name": "Fitness M",
      "billingGroup": {},
      "periods": [
        {
          "id": "<string>",
          "contractPeriodCount": 123,
          "contractPeriod": {},
          "cancellationPeriod": {},
          "createdAt": "2023-11-07T05:31:56Z",
          "updatedAt": "2023-11-07T05:31:56Z"
        }
      ],
      "status": "<any>",
      "activatedAt": "2021-01-01T00:00:00+00:00",
      "poNumber": "PO-00000001",
      "contractDetails": {
        "contractStart": "2023-11-07T05:31:56Z",
        "contractEnd": "2023-11-07T05:31:56Z"
      },
      "trialEndsOn": "2021-01-01T00:00:00+00:00",
      "customFields": {
        "field1": "value1",
        "field2": "value2"
      },
      "createdAt": "2021-01-01T00:00:00+00:00",
      "updatedAt": "2021-01-01T00:00:00+00:00",
      "defaultPaymentMethod": true,
      "defaultInvoiceAddress": true,
      "nextBillingDate": "2023-11-07T05:31:56Z",
      "lastBillingAt": "2023-11-07T05:31:56Z",
      "cancellationDate": "2023-11-07T05:31:56Z",
      "cancelledAt": "2023-11-07T05:31:56Z",
      "isCancellationPending": true,
      "nextPossibleCancellationDate": [
        "<string>"
      ],
      "partner": {
        "id": "ad8f7e7d-3b3b-4b3b-8b3b-3b3b3b3b3b3b",
        "name": "John Doe",
        "number": "123456",
        "email": "partner@example.com"
      }
    }
  ],
  "meta": {
    "pagination": {
      "totalItems": 123,
      "itemsPerPage": 123,
      "currentPage": 123,
      "lastPage": 123,
      "pageTotalItems": 123
    }
  }
}

Authorizations

Authorization

string

header

required

Value for the Authorization header parameter.

Query Parameters

page

integer

default:1

The collection page number

limit

integer

default:30

The number of items per page

Required range: 0 <= x <= 100

string

id[]

string[]

customer

string

customer[]

string[]

number

string

status

string

status[]

string[]

paymentMethod.type

string

paymentMethod.type[]

string[]

items.product.id

string

items.product.id[]

string[]

order[status]

enum<string>

Available options:

asc,

desc

order[createdAt]

enum<string>

Available options:

asc,

desc

order[activatedAt]

enum<string>

Available options:

asc,

desc

order[trialEndsOn]

enum<string>

Available options:

asc,

desc

order[contractDetails.contractEnd]

enum<string>

Available options:

asc,

desc

string

partner

string

Response

200

application/json

Subscription collection

data

object[]

data.id

string

Example:

"ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"

data.externalId

string | null

data.paymentMethod

object | null

The payment method of the subscription. If null, the default payment method of the customer is used.

data.paymentMethod.id

string

data.paymentMethod.gatewayName

enum<string>

Available options:

wallet,

sepa_debit,

stripe,

fake_provider,

paypal,

bank_transfer,

go_cardless,

testing

data.paymentMethod.type

enum<string> | null

Available options:

sepa_debit,

card,

paypal,

bank_transfer,

wallet,

fake_provider

data.paymentMethod.default

boolean

data.paymentMethod.status

enum<string>

default:active

Available options:

active,

action_required,

expired,

revoked,

gateway_unconfigured

Example:

"active"

data.paymentMethod.enabled

boolean

data.paymentMethod.name

string | null

data.paymentMethod.creationDate

string

data.paymentMethod.expirationDate

string | null

data.paymentMethod.card

object

The card data of the payment method, if the type is "card"

data.paymentMethod.sepaDebit

object

The sepa mandate data of the payment method, if the type is "sepa_debit"

data.paymentMethod.paypal

object

The paypal data of the payment method, if the type is "paypal"

data.invoiceAddress

object | null

The invoice address of the subscription. If null, the default invoice address of the customer is used.

data.number

string

The number of the subscription.

Example:

"S-00000001"

data.customer

object

data.plan

object | null

The plan this subscription is based on.

data.plan.id

string

The unique identifier of the plan.

Example:

"ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"

data.plan.family

object | null

Allow to group plans together. This allows to upgrade or downgrade between plans in the same family.

data.plan.code

string

The code of the plan. This is used to identify the plan e.g. in the checkout url.

Example:

"basic-m2023"

data.plan.originProduct

object | null

The origin product this plan belongs to. This is relevant for advanced analytics.

data.plan.originProduct.type

enum<string>

required

The type of the product.

product: recurring billed product
charge: one-time billing
plan: plan specific product, which cannot be used as a normal product. Will be filtered out in any product lists.

Available options:

product,

charge,

plan

data.plan.originProduct.measurement

object

required

The measurement that is used for the price plan. This could define the quantity or a metered usage.

data.plan.originProduct.measurement.unit

object | null

required

The unit of the measurement.

data.plan.originProduct.measurement.code

string

required

A unique code which can be used to identify the measurement.

Required string length: 1 - 255

Example:

"users"

data.plan.originProduct.measurement.id

string

A unique identifier for the measurement.

Example:

"ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"

data.plan.originProduct.measurement.description

string | null

A description of the measurement, which is shown in the summary of the usage data in the invoice.

Maximum length: 255

Example:

"The number of users."

data.plan.originProduct.measurement.aggregationType

any

The aggregation type of the measurement. Describes how the quantity is calculated. This cannot be changed after creation, otherwise it would change the whole calculation for existing subscriptions.

Possible values:

count: The number of sent measurements in the billing interval. Metered usage, which resets to 0 after each billing interval.
count_unique: The number of unique sent measurements in the billing interval, identified by the id given on event creation.
max: The maximum value of all sent measurements in the billing interval. Metered usage, which resets to 0 after each billing interval.
sum: The sum of all sent measurements in the billing interval.
last_value: The last sent measurement.
average: The average of all sent measurements in the billing interval.

data.plan.originProduct.measurement.fairBilling

boolean

default:true

If set to false, the measurement will be billed for the whole billing interval, even if the quantity changes, or the item is cancelled / terminated during the billing interval.

Example:

true

data.plan.originProduct.measurement.type

any

The type of the measurement. This cannot be changed after creation, otherwise it would change the whole calculation for existing subscriptions.

Possible values:

instant_metered: The measurement value is reset to 0 after each push. The measurement gets billed immediately and an invoice is created. The aggregation type must be "last_value".
metered: The measurement value is reset to 0 after each billing interval.
recurring: The measurement value is not reset to 0 after each billing interval and the last value is used for all following billing intervals. The aggregation type must be "last_value".

data.plan.originProduct.taxGroup

object

required

The tax group that is used for the product.

data.plan.originProduct.id

string

The unique identifier of the product.

Example:

"ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"

data.plan.originProduct.name

string

The name of the product based on the current tenant language. This will be displayed on customer communication.

Example:

"Basic"

data.plan.originProduct.description

string | null

The description of the product based on the current tenant language.

Example:

"For small teams."

data.plan.originProduct.internalName

string | null

Internal name of the product, to differentiate between products with the same name. This will shown in web-app lists, selections and reports.

Example:

"Basic (Weekly)"

data.plan.originProduct.invoiceVisibility

enum<string>

Defines when the product should be displayed in the invoice.

always: The product is always displayed in the invoice.
only_if_charged: The product is only displayed in the invoice if it is charged.

Available options:

always,

only_if_charged

data.plan.originProduct.costCentre

object | null

The cost centre is used for accounting exports.

data.plan.originProduct.customFields

object | null

Custom fields for the entity. The keys are the field names and the values are the field values. They need to be configured under "/custom-fields" in the API documentation. The input is validated against the configuration. For more details see Custom Fields Guide

Example:

{ "field1": "value1", "field2": "value2" }

data.plan.allowCheckout

boolean

default:true

Allow to checkout this plan. If this is set to false, the plan will not be available in the checkout and can only be assigned to a subscription by the API or in the admin panel. The plan.code is a part of the checkout url.

Example:

true

data.plan.status

any

The status of the plan.

Possible values:

draft: The plan is a draft and not available for usage in a subscription.
active: The plan is active and can be used in a subscription.
archived: The plan is archived and not longer available for usage in a subscription.
inactive: The plan is inactive and not available for usage in a subscription.

data.plan.changeBehaviour

enum<string>

default:not_changeable

Define the allowed actions after subscription by customer, for upgrade / downgrade.

Available options:

upgradeable,

downgradeable,

upgradeable_and_downgradeable,

not_changeable

Example:

"upgradeable_and_downgradeable"

data.plan.changeApplyBehaviour

enum<string>

default:end_of_period

Define the behaviour when a plan change will be applied. If null the default behaviour will be used.

Available options:

immediately,

end_of_period

Example:

"end_of_period"

data.plan.createdAt

string

data.plan.name

string

The name of this plan

data.plan.description

string | null

The description of this plan

data.name

string | null

The name of the subscription. Defaults to the name of the plan. This will be used in the invoice for the grouping headers.

Example:

"Fitness M"

data.billingGroup

object | null

The billing group defines the billing cycle of the subscription.

data.periods

object[]

data.status

any

The status of the subscription.

Possible values:

draft: The subscription is in draft mode and not active yet.
active: The subscription is active and will be billed.
paused: The subscription is paused and will not be billed.
cancelled: The subscription is cancelled and will not be billed anymore.
terminated: The subscription is terminated and will not be billed anymore.
offer: The subscription is an offer and waiting for acceptance.

data.activatedAt

string | null

The date the subscription was activated.

Example:

"2021-01-01T00:00:00+00:00"

data.poNumber

string | null

The po number of the subscription.

Example:

"PO-00000001"

data.contractDetails

object

The contract details of the subscription.

data.trialEndsOn

string | null

The date the trial period ends.

Example:

"2021-01-01T00:00:00+00:00"

data.customFields

object | null

Example:

{ "field1": "value1", "field2": "value2" }

data.createdAt

string

The date and time when the resource was created.

Example:

"2021-01-01T00:00:00+00:00"

data.updatedAt

string

The date and time when the resource was last updated.

Example:

"2021-01-01T00:00:00+00:00"

data.defaultPaymentMethod

boolean

The payment method is null, we use the default payment method of the customer.

data.defaultInvoiceAddress

boolean

The invoice address is null, we use the default invoice address of the customer.

data.nextBillingDate

string | null

The next billing date of the subscription.

data.lastBillingAt

string | null

The last billing date of the subscription.

data.cancellationDate

string | null

The date the subscription will be cancelled.

data.cancelledAt

string | null

The date when the subscription was cancelled.

data.isCancellationPending

boolean

Indicates if the subscription is pending for cancellation. If true, the subscription will be cancelled in the future and the cancellation could be revoked.

data.nextPossibleCancellationDate

string[] | null

data.partner

object | null

The partner of the customer.

meta

object

Was this page helpful?

Suggest edits Raise issue

Update overdue rule Create subscription

curl -X GET \
 /subscriptions \
 --header "Authorization: Bearer <token>"

{
  "data": [
    {
      "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "externalId": "<string>",
      "paymentMethod": {
        "id": "<string>",
        "gatewayName": "wallet",
        "type": "sepa_debit",
        "default": true,
        "status": "active",
        "enabled": true,
        "name": "<string>",
        "creationDate": "2023-11-07T05:31:56Z",
        "expirationDate": "2023-11-07T05:31:56Z",
        "card": {
          "brand": "Visa",
          "last4": "4242",
          "expMonth": 12,
          "expYear": 2022,
          "cardHolder": "Max Mustermann"
        },
        "sepaDebit": {
          "iban": "DE8937*********3232",
          "bic": "COBADEFFXXX",
          "mandateReference": "MNDT-2021-123456",
          "signingDate": "2021-01-01T00:00:00+00:00"
        },
        "paypal": {
          "email": "max@mustermann.de",
          "billingAgreementId": "I-1J5gqz2eZvKYlo2C2X2X2X2X"
        }
      },
      "invoiceAddress": {
        "id": "<string>",
        "vatId": "DE123456789",
        "type": "TYPE_DEFAULT",
        "default": "true",
        "status": "active",
        "city": "Berlin",
        "zip": "12345",
        "street": "Musterstraße",
        "houseNumber": "1a",
        "countryCode": "DE",
        "companyName": "ACME Inc.",
        "salutation": "Herr",
        "addition": "c/o John Doe",
        "costCentre": "123456789",
        "firstName": "John",
        "lastName": "Doe"
      },
      "number": "S-00000001",
      "customer": {
        "id": "00000000-0000-0000-0000-000000000000",
        "customerNumber": "CUSTOMER-000",
        "timeZone": "Europe/Berlin",
        "firstName": "John",
        "lastName": "Doe",
        "currencyCode": "EUR",
        "companyName": "Acme Inc.",
        "datevId": "123456789",
        "status": "STATUS_ACTIVE"
      },
      "plan": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "family": {
          "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
          "createdAt": "2021-01-01T00:00:00+00:00",
          "updatedAt": "2021-01-01T00:00:00+00:00"
        },
        "code": "basic-m2023",
        "originProduct": {
          "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
          "name": "Basic",
          "description": "For small teams.",
          "internalName": "Basic (Weekly)",
          "type": "product",
          "measurement": {
            "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
            "unit": {
              "id": {},
              "name": "Stück",
              "createdAt": "2021-01-01T00:00:00+00:00",
              "updatedAt": "2021-01-01T00:00:00+00:00"
            },
            "code": "users",
            "description": "The number of users.",
            "aggregationType": "<any>",
            "fairBilling": true,
            "type": "<any>"
          },
          "invoiceVisibility": "always",
          "costCentre": {},
          "taxGroup": {},
          "customFields": {
            "field1": "value1",
            "field2": "value2"
          }
        },
        "allowCheckout": true,
        "status": "<any>",
        "changeBehaviour": "upgradeable_and_downgradeable",
        "changeApplyBehaviour": "end_of_period",
        "createdAt": "2023-11-07T05:31:56Z",
        "name": "<string>",
        "description": "<string>"
      },
      "name": "Fitness M",
      "billingGroup": {},
      "periods": [
        {
          "id": "<string>",
          "contractPeriodCount": 123,
          "contractPeriod": {},
          "cancellationPeriod": {},
          "createdAt": "2023-11-07T05:31:56Z",
          "updatedAt": "2023-11-07T05:31:56Z"
        }
      ],
      "status": "<any>",
      "activatedAt": "2021-01-01T00:00:00+00:00",
      "poNumber": "PO-00000001",
      "contractDetails": {
        "contractStart": "2023-11-07T05:31:56Z",
        "contractEnd": "2023-11-07T05:31:56Z"
      },
      "trialEndsOn": "2021-01-01T00:00:00+00:00",
      "customFields": {
        "field1": "value1",
        "field2": "value2"
      },
      "createdAt": "2021-01-01T00:00:00+00:00",
      "updatedAt": "2021-01-01T00:00:00+00:00",
      "defaultPaymentMethod": true,
      "defaultInvoiceAddress": true,
      "nextBillingDate": "2023-11-07T05:31:56Z",
      "lastBillingAt": "2023-11-07T05:31:56Z",
      "cancellationDate": "2023-11-07T05:31:56Z",
      "cancelledAt": "2023-11-07T05:31:56Z",
      "isCancellationPending": true,
      "nextPossibleCancellationDate": [
        "<string>"
      ],
      "partner": {
        "id": "ad8f7e7d-3b3b-4b3b-8b3b-3b3b3b3b3b3b",
        "name": "John Doe",
        "number": "123456",
        "email": "partner@example.com"
      }
    }
  ],
  "meta": {
    "pagination": {
      "totalItems": 123,
      "itemsPerPage": 123,
      "currentPage": 123,
      "lastPage": 123,
      "pageTotalItems": 123
    }
  }
}

API documentation

User

Tenant

Feature

Entitlement

User & permissions

Settings

Payment

Analytics

Customer

Billing

Dunning

Subscription

Offers

Catalogue

Checkout

Accounting

Taxes

Get all subscriptions

Authorizations

Query Parameters

Response