> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fynn.eu/llms.txt
> Use this file to discover all available pages before exploring further.
# Order products
> Order products for the subscription.
Required permissions: `subscription:write`
## OpenAPI
````yaml post /subscriptions/{id}/products
openapi: 3.1.0
info:
title: Fynn API
description: ''
termsOfService: https://www.fynn.eu/tos
contact:
name: Fynn UG (haftungsbeschränkt)
url: https://www.fynn.eu
email: hi@fynn.eu
license:
name: Proprietary
url: https://www.fynn.eu/license
version: 0.0.0
servers:
- url: https://coreapi.io
description: Production
- url: https://preview.coreapi.io
description: Sandbox
security:
- JWT: []
tags: []
paths:
/subscriptions/{id}/products:
parameters: []
post:
tags:
- Subscription
summary: Order products
description: |-
Order products for the subscription.
Required permissions: `subscription:write`
operationId: orderSubscriptionProducts
parameters:
- name: id
in: path
description: Subscription identifier
required: true
deprecated: false
schema:
type: string
style: simple
explode: false
requestBody:
description: The new Subscription resource
content:
application/json:
schema:
$ref: >-
#/components/schemas/Subscription.OrderSubscriptionProducts-OrderSubscriptionProducts
text/html:
schema:
$ref: >-
#/components/schemas/Subscription.OrderSubscriptionProducts-OrderSubscriptionProducts
required: true
responses:
'201':
description: Subscription resource created
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription-SubscriptionDetail'
text/html:
schema:
$ref: '#/components/schemas/Subscription-SubscriptionDetail'
links: {}
'400':
description: Invalid input
'422':
description: Unprocessable entity
deprecated: false
security:
- JWT:
- subscription:write
x-codeSamples:
- lang: bash
label: cURL
source: |-
curl -X POST \
/subscriptions/{id}/products \
--header "Content-Type: application/json" \
--header "Authorization: Bearer " \
--data '{
"billingStart": "2021-01-01T00:00:00+00:00.000Z",
"startDate": "2021-01-01T00:00:00+00:00.000Z",
"endDate": "2021-01-01T00:00:00+00:00.000Z",
"products": [
[]
]
}'
components:
schemas:
Subscription.OrderSubscriptionProducts-OrderSubscriptionProducts:
type: object
description: ''
deprecated: false
properties:
billingStart:
description: >-
The billing start date of the subscription. Fallback to the start
date if not set.
example: 2021-01-01T00:00:00+00:00.000Z
type:
- string
- 'null'
format: date-time
startDate:
description: >-
The start date of the subscription. If not set, the current date is
used.
example: 2021-01-01T00:00:00+00:00.000Z
type:
- string
- 'null'
format: date-time
endDate:
description: >-
The end date of the subscription. If not set, the subscription has
no end date.
example: 2021-01-01T00:00:00+00:00.000Z
type:
- string
- 'null'
format: date-time
products:
description: The product selections which defines the items of the subscription.
type: array
items:
$ref: '#/components/schemas/ProductSelection-OrderSubscriptionProducts'
Subscription-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
example: ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b
type: string
externalId:
type:
- string
- 'null'
paymentMethod:
description: >-
The payment method of the subscription. If null, the default payment
method of the customer is used.
anyOf:
- $ref: '#/components/schemas/PaymentMethod-SubscriptionDetail'
- type: 'null'
invoiceAddress:
description: >-
The invoice address of the subscription. If null, the default
invoice address of the customer is used.
anyOf:
- $ref: '#/components/schemas/CustomerAddress-SubscriptionDetail'
- type: 'null'
number:
description: The number of the subscription.
example: S-00000001
type: string
customer:
$ref: '#/components/schemas/Customer-SubscriptionDetail'
plan:
readOnly: true
description: The plan this subscription is based on.
anyOf:
- $ref: '#/components/schemas/Plan-SubscriptionDetail'
- type: 'null'
name:
description: >-
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
type:
- string
- 'null'
items:
description: The selected items of the subscription. Can be charges or addons.
type: array
items:
$ref: '#/components/schemas/SubscriptionItem-SubscriptionDetail'
billingGroup:
description: The billing group defines the billing cycle of the subscription.
anyOf:
- $ref: '#/components/schemas/BillingGroup-SubscriptionDetail'
- type: 'null'
periods:
type: array
items:
$ref: '#/components/schemas/TermPeriod-SubscriptionDetail'
status:
readOnly: true
description: |-
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.
example: active
activatedAt:
readOnly: true
description: The date the subscription was activated.
example: '2021-01-01T00:00:00+00:00'
type:
- string
- 'null'
format: date-time
poNumber:
description: The po number of the subscription.
example: PO-00000001
type:
- string
- 'null'
contractDetails:
$ref: '#/components/schemas/ContractDetails-SubscriptionDetail'
description: The contract details of the subscription.
trialEndsOn:
readOnly: true
description: The date the trial period ends.
example: '2021-01-01T00:00:00+00:00'
type:
- string
- 'null'
format: date-time
customFields:
additionalProperties:
type: string
type:
- object
- 'null'
example:
field1: value1
field2: value2
description: >-
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](/guide/tenant/custom-fields)
createdAt:
readOnly: true
description: The date and time when the resource was created.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
updatedAt:
readOnly: true
description: The date and time when the resource was last updated.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
defaultPaymentMethod:
readOnly: true
description: >-
The payment method is null, we use the default payment method of the
customer.
type: boolean
defaultInvoiceAddress:
readOnly: true
description: >-
The invoice address is null, we use the default invoice address of
the customer.
type: boolean
nextBillingDate:
readOnly: true
description: The next billing date of the subscription.
type:
- string
- 'null'
format: date-time
lastBillingAt:
readOnly: true
description: The last billing date of the subscription.
type:
- string
- 'null'
format: date-time
cancellationDate:
readOnly: true
description: The date the subscription will be cancelled.
type:
- string
- 'null'
format: date-time
cancelledAt:
readOnly: true
description: The date when the subscription was cancelled.
type:
- string
- 'null'
format: date-time
cancellationReason:
readOnly: true
description: The reason why the subscription was cancelled.
anyOf:
- $ref: '#/components/schemas/CancellationReason-SubscriptionDetail'
- type: 'null'
isCancellationPending:
readOnly: true
description: >-
Indicates if the subscription is pending for cancellation. If true,
the subscription will be cancelled in the future and the
cancellation could be revoked.
type: boolean
nextPossibleCancellationDate:
readOnly: true
type:
- array
- 'null'
items:
type: string
partner:
readOnly: true
description: The partner of the customer.
anyOf:
- $ref: '#/components/schemas/PartnerResource-SubscriptionDetail'
- type: 'null'
ProductSelection-OrderSubscriptionProducts:
type: object
description: ''
deprecated: false
required:
- product
properties:
product:
description: The product to select.
nullable: false
quantity:
description: >-
The quantity of the product. If the product uses a measurement with
type "metered" or "instant_metered", this value sets the initial
value of the measurement.
example: 1
nullable: false
customPricePlan:
description: >-
Overrides the price plan. Allows to define a custom price plan for
the subscription product.
anyOf:
- $ref: '#/components/schemas/PricePlan-OrderSubscriptionProducts'
- type: 'null'
pricePlan:
description: >-
The price plan of the product.
This is necessary to allow bulk updates of the price for
subscriptions, e.g. when the price of a product changes. Also
necessary for statistics.
nullable: false
periods:
description: >-
The contract period terms of the subscription item. If none
provided, the contract period terms of the subscription are used.
type: array
items:
$ref: >-
#/components/schemas/ContractPeriodTermInput-OrderSubscriptionProducts
customName:
maxLength: 255
description: The custom name of the item which is displayed in the invoice.
example: My custom name
type:
- string
- 'null'
customDescription:
description: >-
The custom description of the item which is displayed in the
invoice.
example: My custom description
type:
- string
- 'null'
children:
description: The children of the subscription item. Max depth is 1.
type: array
items:
$ref: '#/components/schemas/ProductSelection-OrderSubscriptionProducts'
discount:
description: The discount of the subscription item.
anyOf:
- $ref: '#/components/schemas/DiscountInput-OrderSubscriptionProducts'
- type: 'null'
autoAssignProductGroup:
description: >-
If set to true, the product group will be automatically assigned
based on the product. Defaults to false.
type: boolean
default: false
PaymentMethod-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
type: string
description: Unique identifier of the payment method
example: c1a2b3c4-d5e6-4f7a-8b9b-0c1d2e3f4a5b
gatewayName:
type: string
enum:
- wallet
- sepa_debit
- stripe
- fake_provider
- paypal
- bank_transfer
- go_cardless
- testing
description: The payment gateway used to process the payment method
type:
type:
- string
- 'null'
enum:
- sepa_debit
- card
- paypal
- bank_transfer
- wallet
- fake_provider
- null
description: The type of the payment method
default:
type: boolean
description: Whether this is the default payment method for the customer
example: true
status:
default: active
example: active
type: string
enum:
- active
- action_required
- expired
- revoked
- gateway_unconfigured
description: The current status of the payment method
enabled:
type: boolean
description: Whether the payment method is enabled for use
example: true
name:
type:
- string
- 'null'
description: Display name of the payment method
example: Visa (4242)
creationDate:
readOnly: true
type: string
format: date-time
description: The date when the payment method was created
example: '2024-01-15T10:30:00+00:00'
expirationDate:
type:
- string
- 'null'
format: date-time
description: The expiration date of the payment method, if applicable
example: '2026-12-31T23:59:59+00:00'
card:
readOnly: true
description: The card data of the payment method, if the type is "card"
type: object
properties:
brand:
type: string
example: Visa
description: The brand of the card
last4:
type: string
example: '4242'
description: The last 4 digits of the card
expMonth:
type: integer
example: 12
description: The expiration month of the card
expYear:
type: integer
example: 2022
description: The expiration year of the card
cardHolder:
type: string
example: Max Mustermann
description: The card holder name
sepaDebit:
readOnly: true
description: >-
The sepa mandate data of the payment method, if the type is
"sepa_debit"
type: object
properties:
iban:
type: string
example: DE8937*********3232
description: The iban of the sepa mandate
bic:
type: string
example: COBADEFFXXX
description: The bic of the sepa mandate
mandateReference:
type: string
example: MNDT-2021-123456
description: The mandate reference of the sepa mandate
signingDate:
type: string
example: '2021-01-01T00:00:00+00:00'
description: The signing date of the sepa mandate
paypal:
readOnly: true
description: The paypal data of the payment method, if the type is "paypal"
type: object
properties:
email:
type: string
example: max@mustermann.de
description: The email of the paypal account
billingAgreementId:
type: string
example: I-1J5gqz2eZvKYlo2C2X2X2X2X
description: The billing agreement id of the paypal account
CustomerAddress-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
type: string
vatId:
description: >-
VAT ID, which will be used to bill to. If not provided, we will use
the customer vat id.
example: DE123456789
type:
- string
- 'null'
type:
example: TYPE_DEFAULT
enum:
- TYPE_DEFAULT
- TYPE_INVOICE
default:
example: 'true'
type: boolean
status:
readOnly: true
example: active
enum:
- active
- archived
city:
example: Berlin
type: string
zip:
example: '12345'
type: string
street:
example: Musterstraße
type: string
houseNumber:
example: 1a
type: string
countryCode:
example: DE
type: string
companyName:
description: Company name, which will be used to bill to.
example: ACME Inc.
type:
- string
- 'null'
salutation:
example: Herr
enum:
- Firma
- Herr
- Frau
addition:
description: >-
Additional address information, which will be shown on generated
documents like invoices, reminders, etc.
example: c/o John Doe
type:
- string
- 'null'
costCentre:
description: >-
Cost centre, which will be shown on generated documents like
invoices, reminders, etc.
example: '123456789'
type:
- string
- 'null'
firstName:
description: >-
First name, which will be shown on generated documents like
invoices, reminders, etc.
example: John
type:
- string
- 'null'
lastName:
description: >-
Last name, which will be shown on generated documents like invoices,
reminders, etc.
example: Doe
type:
- string
- 'null'
Customer-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
example: 00000000-0000-0000-0000-000000000000
type: string
customerNumber:
minLength: 2
maxLength: 255
example: CUSTOMER-000
nullable: false
timeZone:
readOnly: true
default: Europe/Berlin
example: Europe/Berlin
type: string
firstName:
minLength: 2
maxLength: 255
description: Can be empty if the customer is a company.
example: John
nullable: true
lastName:
minLength: 2
maxLength: 255
description: Can be empty if the customer is a company.
example: Doe
nullable: true
currencyCode:
description: >-
Can be empty. In this case the default currency of the tenant is
used.
externalDocs:
url: https://schema.org/priceCurrency
example: EUR
type: string
companyName:
minLength: 2
maxLength: 255
example: Acme Inc.
type:
- string
- 'null'
datevId:
minLength: 2
maxLength: 255
description: The ID of the customer in DATEV
example: '123456789'
type:
- string
- 'null'
status:
default: STATUS_ACTIVE
example: STATUS_ACTIVE
enum:
- STATUS_ACTIVE
- STATUS_ARCHIVED
- STATUS_SUSPENDED
Plan-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
description: The unique identifier of the plan.
example: ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b
type: string
family:
description: >-
Allow to group plans together. This allows to upgrade or downgrade
between plans in the same family.
anyOf:
- $ref: '#/components/schemas/PlanFamily-SubscriptionDetail'
- type: 'null'
code:
description: >-
The code of the plan. This is used to identify the plan e.g. in the
checkout url.
example: basic-m2023
type: string
originProduct:
readOnly: true
description: >-
The origin product this plan belongs to. This is relevant for
advanced analytics.
anyOf:
- $ref: '#/components/schemas/Product-SubscriptionDetail'
- type: 'null'
allowCheckout:
description: >-
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.
default: true
example: true
type: boolean
status:
readOnly: true
description: |-
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.
default: draft
example: draft
changeBehaviour:
description: >-
Define the allowed actions after subscription by customer, for
upgrade / downgrade.
default: not_changeable
example: upgradeable_and_downgradeable
type: string
enum:
- upgradeable
- downgradeable
- upgradeable_and_downgradeable
- not_changeable
changeApplyBehaviour:
description: >-
Define the behaviour when a plan change will be applied. If null the
default behaviour will be used.
default: end_of_period
example: end_of_period
type: string
enum:
- immediately
- end_of_period
createdAt:
type: string
format: date-time
name:
readOnly: true
description: The name of this plan
type: string
description:
readOnly: true
description: The description of this plan
type:
- string
- 'null'
SubscriptionItem-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
example: 01F9ZQZJZJQZJZJZJZJZJZJZJZ
type: string
parent:
readOnly: true
description: >-
The parent item of the item. If this is null, the item is a root
item.
anyOf:
- $ref: '#/components/schemas/SubscriptionItem-SubscriptionDetail'
- type: 'null'
plan:
readOnly: true
description: The plan this item is based on.
anyOf:
- $ref: '#/components/schemas/Plan-SubscriptionDetail'
- type: 'null'
measurementValues:
readOnly: true
description: Usage values during the subscription item period.
type: array
items:
$ref: '#/components/schemas/MeasurementValue-SubscriptionDetail'
billing:
$ref: '#/components/schemas/Billing-SubscriptionDetail'
readOnly: true
description: The billing details of the item.
name:
readOnly: true
description: >-
The name of the item which will be used in the invoice. The name is
translated based on the customer's locale.
example: Fitness M
type: string
description:
readOnly: true
description: >-
The description of the item which will be used in the invoice. The
description is translated based on the customer's locale.
example: Everything included
type:
- string
- 'null'
furtherInformation:
readOnly: true
description: >-
Further information defines additional information for the item
which will be displayed in the invoice.
example: 'Additional agreements: The contract includes a free drink flatrate.'
type:
- string
- 'null'
pricePlan:
readOnly: true
description: >-
The price plan of the item, which defines the price and billing
interval.
anyOf:
- $ref: '#/components/schemas/PricePlan-SubscriptionDetail'
- type: 'null'
status:
readOnly: true
description: |-
The status of the item.
Possible values:
* `active`: The item is active and will be billed.
* `canceled`: The item is canceled and will be billed until the end of the contract.
* `pending`: The item is pending and will be billed after the contract start.
* `terminated`: The item is terminated and will not be billed.
example: active
enum:
- active
- canceled
- pending
- terminated
product:
readOnly: true
description: The product of the item.
anyOf:
- $ref: '#/components/schemas/Product-SubscriptionDetail'
- type: 'null'
appliedDiscounts:
readOnly: true
type: array
items:
$ref: >-
#/components/schemas/SubscriptionItemAppliedDiscount-SubscriptionDetail
periods:
type: array
items:
$ref: '#/components/schemas/TermPeriod-SubscriptionDetail'
activatedAt:
readOnly: true
description: The date the subscription item was activated.
example: '2021-01-01T00:00:00+00:00'
type:
- string
- 'null'
format: date-time
type:
readOnly: true
description: |-
The type of the item.
Possible values:
* `option`: The item is an product set option.
* `charge`: The item is a charge.
* `plan-product`: The item is a plan product.
* `product`: The item is a product, and not created from a plan.
example: addon
enum:
- addon
- charge
- plan-product
- product
currentMeasurementValue:
readOnly: true
description: The current measurement value of the item.
anyOf:
- $ref: '#/components/schemas/MeasurementValue-SubscriptionDetail'
- type: 'null'
inheritedPeriod:
readOnly: true
description: Is the period inherited from the subscription?
example: true
type: boolean
BillingGroup-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
example: 01F9ZQZJZJQZJZJZJZJZJZJZJZ
type: string
name:
maxLength: 255
description: The name of the billing group.
example: Billing of payments at the end of the month
type: string
type:
readOnly: true
description: |-
The type of the billing group.
Possible values:
* `start_of_month`: The billing group will be charged on the first day of the month.
* `end_of_month`: The billing group will be charged on the last day of the month.
* `start_of_year`: The billing group will be charged on the first day of the year.
* `end_of_year`: The billing group will be charged on the last day of the year.
* `custom`: The billing group will be charged on a custom day of the month.
example: end_of_month
customDay:
exclusiveMinimum: 0
maximum: 31
readOnly: true
description: >-
The custom day of the billing group, only used when type is
"custom".
example: 31
type:
- integer
- 'null'
customMonth:
exclusiveMinimum: 0
maximum: 12
readOnly: true
description: >-
The custom month of the billing group, only used when type is
"custom".
example: 12
type:
- integer
- 'null'
required:
- name
- type
TermPeriod-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
type: string
contractPeriodCount:
readOnly: true
type: integer
contractPeriod:
$ref: '#/components/schemas/Interval-SubscriptionDetail'
readOnly: true
cancellationPeriod:
$ref: '#/components/schemas/Interval-SubscriptionDetail'
readOnly: true
createdAt:
readOnly: true
type: string
format: date-time
updatedAt:
readOnly: true
type: string
format: date-time
ContractDetails-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
contractStart:
description: The start of the contract.
type: string
format: date-time
contractEnd:
description: The end of the contract.
type:
- string
- 'null'
format: date-time
CancellationReason-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
type: string
code:
maxLength: 255
pattern: ^([a-zA-Z0-9_]+)$
description: >-
The code of the cancellation reason. This code is used for easier
reference and should be unique within the tenant.
type: string
name:
maxLength: 255
description: >-
The name of the cancellation reason. This is a human readable name
for the cancellation reason.
type: string
createdAt:
readOnly: true
description: The date and time when the resource was created.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
updatedAt:
readOnly: true
description: The date and time when the resource was last updated.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
required:
- code
- name
PartnerResource-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
id:
description: The ID of the partner
example: ad8f7e7d-3b3b-4b3b-8b3b-3b3b3b3b3b3b
type: string
name:
description: The name of the partner
example: John Doe
type: string
number:
description: The customer number of the partner
example: '123456'
type: string
email:
description: The email address of the partner
example: partner@example.com
type:
- string
- 'null'
PricePlan-OrderSubscriptionProducts:
type: object
description: ''
deprecated: false
properties:
internalName:
minLength: 3
maxLength: 255
description: The internal name of the price plan.
example: Exclusive pricing for partners.
type:
- string
- 'null'
type:
description: |-
The type of the charge. This defines how the price is calculated.
Possible values:
* `flat_fee`: A flat fee is charged, e.g. 10€ per month independent of the number of units.
* `volume`: A volume based price is charged, e.g. 10€ for the first 10 units and 9€ for all units when the number of units is above 10. Useful for volume discounts.
* `percentage`: A percentage of the total price is charged, e.g. 10% of the total price multiplied by the number of units. Useful for provisions.
* `per_unit`: A price per unit is charged, e.g. 10€ per unit per billing interval. Useful for per seat based pricing.
* `tiered`: A tiered price is charged. E.g. 10€ per unit for the first 10 units, 9€ per unit for the next 10 units and 8€ per unit for all units above 20.
* `stair_step`: A stair step price is charged. E.g. 10€ per unit for the first 10 units, 9€ per unit for all units above 10.
example: flat_fee
applyTrial:
description: >-
If this is set to true, the price plan can be applied on a trial. If
the product is in trial, and this is false, the price will be
charged on subscription start, otherwise after trial.
default: true
example: true
type: boolean
payInAdvance:
description: >-
If this is set to true, the price will be charged in advance. If
this is false, the price will be charged at the end of the billing
interval.
default: true
example: true
type:
- boolean
- 'null'
proRata:
description: >-
If this is set to true, the price will be charged prorated when a
partial billing interval is billed. This applies to measurements of
type "recurring" or non-one-time billing intervals. For other
measurements this parameter will be ignored.
type: boolean
freeUnits:
description: >-
The amount of free units. If null, no free units are available. Free
units will be applied before passed to the price calculation and are
available prorated.
If the customer does not uses the free units during a billing
period, they are not carried over to the next billing period.
If the customer cancels the subscription before ending the billing
period, the free units are only available prorated for the remaining
billing period.
**Example**: You offer 2400 free units for 12 months and your price
has a billing interval for 1 month. The customer cancels after 6
months. Only 1200 free units are available.
**A price plan for a recurring product cannot have free units. Use a
metered product instead.**
**A price plan related to a product of type charge cannot have free
units.**
anyOf:
- $ref: '#/components/schemas/Quantity-OrderSubscriptionProducts'
- type: 'null'
billingInterval:
description: >-
The billing interval of the price plan. If null, this is a one-time
charge.
Billing intervals of null cannot be prorated.
example: 1M
anyOf:
- $ref: '#/components/schemas/BillingInterval-OrderSubscriptionProducts'
- type: 'null'
showPricePerInterval:
description: >-
Display the billed price per interval in customerfront or invoices.
If null, the price will be shown per billing interval.
Currently only available for billing intervals of months, years.
Currently only allowed to show price per month (1M)
example: 1M
anyOf:
- $ref: '#/components/schemas/Interval-OrderSubscriptionProducts'
- type: 'null'
currencyCode:
$ref: '#/components/schemas/CurrencyCode-OrderSubscriptionProducts'
description: The currency of the price
price:
description: The price in the defined billing interval.
type: object
oneOf:
- $ref: '#/components/schemas/FlatFeePrice'
title: Flat fee
- $ref: '#/components/schemas/PercentagePrice'
title: Percentage
- $ref: '#/components/schemas/PerUnitPrice'
title: Per unit
- $ref: '#/components/schemas/TieredPrice'
title: Tiered
required:
- type
- currencyCode
- price
ContractPeriodTermInput-OrderSubscriptionProducts:
type: object
description: ''
deprecated: false
required:
- contractPeriod
- cancellationPeriod
properties:
contractPeriod:
$ref: '#/components/schemas/Interval-OrderSubscriptionProducts'
description: The contract period of the subscription.
example: 1M
cancellationPeriod:
$ref: '#/components/schemas/Interval-OrderSubscriptionProducts'
description: The cancellation period of the subscription.
example: 1M
DiscountInput-OrderSubscriptionProducts:
type: object
description: ''
deprecated: false
properties:
coupon:
description: >-
The coupon of the discount. If none provided, the discount is
applied without a coupon relation, which means that the discount is
not visible in any statistics.
type:
- string
- 'null'
format: uuid
example: https://example.com/
fixedAmount:
description: >-
The fixed amount of the discount. This is only applicable for fixed
amount discounts with type "fixed_amount".
example:
amount: 10.29
currency: EUR
type:
- array
- 'null'
items:
type: string
frequency:
enum:
- lifetime
- once
- limited
description: The frequency how often the discount is applied.
default: once
example: once
type: string
frequencyInterval:
description: >-
The frequency interval how often the discount is applied. This is
only applicable for limited recurring discounts.
example: 1
type:
- integer
- 'null'
name:
maxLength: 255
description: >-
The name of the discount. This is displayed in the customer portal
and in the invoice.
example: My discount
type: string
percentage:
minimum: 0
maximum: 100
description: >-
The percentage of the discount. This is only applicable for
percentage discounts with type "percentage".
example: 10.29
type:
- number
- 'null'
type:
enum:
- fixed_amount
- percentage
description: The type of the discount.
default: fixed_amount
example: fixed_amount
type: string
required:
- name
PlanFamily-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
example: ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b
type: string
createdAt:
readOnly: true
description: The date and time when the resource was created.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
updatedAt:
readOnly: true
description: The date and time when the resource was last updated.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
Product-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
description: The unique identifier of the product.
example: ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b
type: string
name:
description: >-
The name of the product based on the current tenant language. This
will be displayed on customer communication.
example: Basic
type: string
description:
description: The description of the product based on the current tenant language.
example: For small teams.
type:
- string
- 'null'
internalName:
description: >-
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)
type:
- string
- 'null'
type:
description: |
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.
type: string
enum:
- product
- charge
- plan
measurement:
$ref: '#/components/schemas/Measurement-SubscriptionDetail'
description: >-
The measurement that is used for the price plan. This could define
the quantity or a metered usage.
invoiceVisibility:
description: |
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.
type: string
enum:
- always
- only_if_charged
costCentre:
description: The cost centre is used for accounting exports.
anyOf:
- $ref: '#/components/schemas/CostCentre-SubscriptionDetail'
- type: 'null'
taxGroup:
$ref: '#/components/schemas/TaxGroup-SubscriptionDetail'
description: The tax group that is used for the product.
customFields:
additionalProperties:
type: string
type:
- object
- 'null'
example:
field1: value1
field2: value2
description: >-
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](/guide/tenant/custom-fields)
required:
- type
- measurement
- taxGroup
MeasurementValue-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
example: ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b
type: string
measurement:
$ref: '#/components/schemas/Measurement-SubscriptionDetail'
description: The measurement of the item.
quantity:
$ref: '#/components/schemas/Quantity-SubscriptionDetail'
description: The tracked and measured quantity of the item.
example: 1
measuredAt:
description: The date and time when the measurement was taken.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
Billing-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
lastBilledAt:
readOnly: true
type:
- string
- 'null'
format: date-time
lastBilledTo:
readOnly: true
type:
- string
- 'null'
format: date-time
lastBilledFrom:
readOnly: true
type:
- string
- 'null'
format: date-time
nextBillingAt:
readOnly: true
type:
- string
- 'null'
format: date-time
billingInterval:
description: |
The billing interval of the item.
If the value is null, the item is billed only once (one-time).
If the value is not null, the item is billed periodically.
The value is a string in the following format: [number][unit]
The unit can be one of the following: H, D, W, M, Y
example: 1M
anyOf:
- $ref: '#/components/schemas/BillingInterval-SubscriptionDetail'
- type: 'null'
PricePlan-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
description: The unique identifier of the price plan.
example: ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b
type: string
internalName:
minLength: 3
maxLength: 255
description: The internal name of the price plan.
example: Exclusive pricing for partners.
type:
- string
- 'null'
status:
readOnly: true
description: |-
The status of the price plan.
Possible values:
* `active`: The price is active and can be used.
* `archived`: The price is archived and cannot be used anymore. It will be not shown in any lists until explicitly requested.
default: active
example: active
type:
description: |-
The type of the charge. This defines how the price is calculated.
Possible values:
* `flat_fee`: A flat fee is charged, e.g. 10€ per month independent of the number of units.
* `volume`: A volume based price is charged, e.g. 10€ for the first 10 units and 9€ for all units when the number of units is above 10. Useful for volume discounts.
* `percentage`: A percentage of the total price is charged, e.g. 10% of the total price multiplied by the number of units. Useful for provisions.
* `per_unit`: A price per unit is charged, e.g. 10€ per unit per billing interval. Useful for per seat based pricing.
* `tiered`: A tiered price is charged. E.g. 10€ per unit for the first 10 units, 9€ per unit for the next 10 units and 8€ per unit for all units above 20.
* `stair_step`: A stair step price is charged. E.g. 10€ per unit for the first 10 units, 9€ per unit for all units above 10.
example: flat_fee
applyTrial:
description: >-
If this is set to true, the price plan can be applied on a trial. If
the product is in trial, and this is false, the price will be
charged on subscription start, otherwise after trial.
default: true
example: true
type: boolean
payInAdvance:
description: >-
If this is set to true, the price will be charged in advance. If
this is false, the price will be charged at the end of the billing
interval.
default: true
example: true
type:
- boolean
- 'null'
proRata:
description: >-
If this is set to true, the price will be charged prorated when a
partial billing interval is billed. This applies to measurements of
type "recurring" or non-one-time billing intervals. For other
measurements this parameter will be ignored.
type: boolean
freeUnits:
description: >-
The amount of free units. If null, no free units are available. Free
units will be applied before passed to the price calculation and are
available prorated.
If the customer does not uses the free units during a billing
period, they are not carried over to the next billing period.
If the customer cancels the subscription before ending the billing
period, the free units are only available prorated for the remaining
billing period.
**Example**: You offer 2400 free units for 12 months and your price
has a billing interval for 1 month. The customer cancels after 6
months. Only 1200 free units are available.
**A price plan for a recurring product cannot have free units. Use a
metered product instead.**
**A price plan related to a product of type charge cannot have free
units.**
anyOf:
- $ref: '#/components/schemas/Quantity-SubscriptionDetail'
- type: 'null'
billingInterval:
description: >-
The billing interval of the price plan. If null, this is a one-time
charge.
Billing intervals of null cannot be prorated.
example: 1M
anyOf:
- $ref: '#/components/schemas/BillingInterval-SubscriptionDetail'
- type: 'null'
showPricePerInterval:
description: >-
Display the billed price per interval in customerfront or invoices.
If null, the price will be shown per billing interval.
Currently only available for billing intervals of months, years.
Currently only allowed to show price per month (1M)
example: 1M
anyOf:
- $ref: '#/components/schemas/Interval-SubscriptionDetail'
- type: 'null'
currencyCode:
$ref: '#/components/schemas/CurrencyCode-SubscriptionDetail'
description: The currency of the price
price:
description: The price in the defined billing interval.
type: object
oneOf:
- $ref: '#/components/schemas/FlatFeePrice'
title: Flat fee
- $ref: '#/components/schemas/PercentagePrice'
title: Percentage
- $ref: '#/components/schemas/PerUnitPrice'
title: Per unit
- $ref: '#/components/schemas/TieredPrice'
title: Tiered
custom:
readOnly: true
description: >-
If this price plan is a custom price plan. A price plan is custom if
it is defined specific for a plan addon, plan charge, customer or
sales channel.
example: true
type: boolean
charge:
$ref: '#/components/schemas/PlanCharge-SubscriptionDetail'
description: The charge related to this price plan.
example: ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b
productSetOption:
$ref: '#/components/schemas/PlanProductSetOption-SubscriptionDetail'
description: The product set option related to this price plan.
example: ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b
inUse:
readOnly: true
description: If this price plan is in use.
example: true
type: boolean
required:
- type
- currencyCode
- price
SubscriptionItemAppliedDiscount-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
type: string
coupon:
readOnly: true
anyOf:
- $ref: '#/components/schemas/Coupon-SubscriptionDetail'
- type: 'null'
status:
readOnly: true
description: |-
The status of this applied discount.
Possible values:
* `active`: The discount is active and will be applied to the subscription item.
* `completed`: The discount is not active anymore, but it was applied to the subscription item.
* `removed`: The discount was removed from the subscription item.
example: active
discount:
$ref: '#/components/schemas/Discount-SubscriptionDetail'
readOnly: true
description: The discount that is applied to the subscription item.
appliedIntervals:
readOnly: true
description: >-
The number of intervals this discount was applied to the
subscription item.
example: 1
type:
- integer
- 'null'
Interval-SubscriptionDetail:
type: object
description: ''
deprecated: false
Quantity-OrderSubscriptionProducts:
type:
- number
- 'null'
description: A numeric quantity value.
example: 1
BillingInterval-OrderSubscriptionProducts:
type: object
description: ''
deprecated: false
Interval-OrderSubscriptionProducts:
type: object
description: ''
deprecated: false
CurrencyCode-OrderSubscriptionProducts:
type: string
description: ISO 4217 currency code.
example: EUR
FlatFeePrice:
type: object
description: ''
deprecated: false
required:
- amount
properties:
amount:
description: The amount of the flat fee per unit
type: number
createdAt:
readOnly: true
description: The date and time when the resource was created.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
updatedAt:
readOnly: true
description: The date and time when the resource was last updated.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
tenantId:
readOnly: true
type: string
title: Flat fee
PercentagePrice:
type: object
description: ''
deprecated: false
required:
- percentage
- fixedAmount
- freeUnitsPerEvent
- freeUnitsPerBillingInterval
properties:
percentage:
description: The percentage of the total amount that is charged.
type: number
fixedAmount:
description: >-
The fixed amount that is charged per unit, metered in the billing
period. E.g. on pushing 1000 units, the fixed amount is charged 1000
times * percentage
type: number
freeUnitsPerEvent:
description: The number of units that are not subject to the fixed fee.
type: integer
freeUnitsPerBillingInterval:
description: The amount that is not subject to the charge rate.
type: number
createdAt:
readOnly: true
description: The date and time when the resource was created.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
updatedAt:
readOnly: true
description: The date and time when the resource was last updated.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
tenantId:
readOnly: true
type: string
title: Percentage
PerUnitPrice:
type: object
description: ''
deprecated: false
required:
- amount
properties:
amount:
description: The amount of money per unit
example: 0.99
type: number
createdAt:
readOnly: true
description: The date and time when the resource was created.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
updatedAt:
readOnly: true
description: The date and time when the resource was last updated.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
tenantId:
readOnly: true
type: string
title: Per unit
TieredPrice:
type: object
description: ''
deprecated: false
required:
- items
properties:
items:
minItems: 1
type: array
items:
$ref: '#/components/schemas/TierItem'
createdAt:
readOnly: true
description: The date and time when the resource was created.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
updatedAt:
readOnly: true
description: The date and time when the resource was last updated.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
tenantId:
readOnly: true
type: string
title: Tiered
Measurement-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
description: A unique identifier for the measurement.
example: ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b
type: string
unit:
description: The unit of the measurement.
anyOf:
- $ref: '#/components/schemas/Unit-SubscriptionDetail'
- type: 'null'
code:
minLength: 1
maxLength: 255
description: A unique code which can be used to identify the measurement.
example: users
type: string
description:
maxLength: 255
description: >-
A description of the measurement, which is shown in the summary of
the usage data in the invoice.
example: The number of users.
type:
- string
- 'null'
aggregationType:
description: >-
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.
default: last_value
example: sum
fairBilling:
description: >-
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.
default: true
example: true
type: boolean
type:
description: >-
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".
default: recurring
example: recurring
required:
- unit
- code
CostCentre-SubscriptionDetail:
type: object
description: ''
deprecated: false
TaxGroup-SubscriptionDetail:
type: object
description: ''
deprecated: false
Quantity-SubscriptionDetail:
type:
- number
- 'null'
description: A numeric quantity value.
example: 1
BillingInterval-SubscriptionDetail:
type: object
description: ''
deprecated: false
CurrencyCode-SubscriptionDetail:
type: string
description: ISO 4217 currency code.
example: EUR
PlanCharge-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
description: The unique identifier of the plan product.
type: string
product:
$ref: '#/components/schemas/Product-SubscriptionDetail'
readOnly: true
description: The product this addon belongs to.
onEvent:
description: >-
The event on which the charge should be applied. Defaults to
ON_SUBSCRIPTION_START.
Possible values:
* `on_subscription_start`: The charge is applied when the subscription starts.
* `on_subscription_end`: The charge is applied when the subscription ends.
* `on_subscription_trial_start`: The charge is applied when the subscription trial starts.
* `on_subscription_trial_end`: The charge is applied when the subscription trial ends.
* `on_checkout_payment`: The charge is applied when the checkout payment is made.
default: on_subscription_start
example: on_subscription_start
onceOnEvent:
description: >-
Whether the charge should only be applied once on the event.
Defaults to false.
type: boolean
PlanProductSetOption-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
description: The unique identifier of the product set option.
example: ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b
type: string
product:
$ref: '#/components/schemas/Product-SubscriptionDetail'
description: The product this option belongs to.
Coupon-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
description: The id of this coupon.
type: string
code:
description: >-
The code that can be used to apply this coupon or to use it with the
api.
example: 10OFF
type: string
name:
description: >-
The name of this coupon, which will be displayed to the user in the
checkout process, customer front, etc.
example: 10% off
type: string
type:
description: |-
The type of this coupon.
Possible values:
* `percentage`: A percentage will be taken off the total plan amount.
* `fixed_amount`: A fixed amount will be taken off the total plan amount. It will never go below 0.
example: percentage
percentage:
minimum: 0
maximum: 100
description: >-
The percentage this coupon should apply. **Required for type
`percentage`.**
example: 10
type:
- integer
- 'null'
fixedAmount:
$ref: '#/components/schemas/MoneyEmbeddedDefaultNull-SubscriptionDetail'
description: >-
The fixed amount this coupon should apply. **Required for type
`fixed_amount`.**
frequency:
description: |-
The frequency at which a coupon should be applied.
Possible values:
* `once`: The coupon will be applied once for the first billing period.
* `limited`: The coupon will be applied for a limited number of billing periods.
* `lifetime`: The coupon will be applied forever.
example: limited
frequencyInterval:
description: >-
The number of billing periods the coupon will be applied for.
**Required for frequency `limited`.**
example: 3
type:
- integer
- 'null'
isEnabled:
description: Whether this coupon is enabled or not.
default: true
example: true
type: boolean
createdAt:
readOnly: true
description: The date and time when the resource was created.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
updatedAt:
readOnly: true
description: The date and time when the resource was last updated.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
required:
- code
- name
- type
- frequency
Discount-SubscriptionDetail:
type: object
description: ''
deprecated: false
required:
- name
- type
- frequency
properties:
name:
description: >-
The name of this coupon, which will be displayed to the user in the
checkout process, customer front, etc.
example: 10% off
type: string
type:
description: |-
The type of this coupon.
Possible values:
* `percentage`: A percentage will be taken off the total plan amount.
* `fixed_amount`: A fixed amount will be taken off the total plan amount. It will never go below 0.
example: percentage
percentage:
minimum: 0
maximum: 100
description: >-
The percentage this coupon should apply. **Required for type
`percentage`.**
example: 10
type:
- integer
- 'null'
fixedAmount:
$ref: '#/components/schemas/MoneyEmbeddedDefaultNull-SubscriptionDetail'
description: >-
The fixed amount this coupon should apply. **Required for type
`fixed_amount`.**
frequency:
description: |-
The frequency at which a coupon should be applied.
Possible values:
* `once`: The coupon will be applied once for the first billing period.
* `limited`: The coupon will be applied for a limited number of billing periods.
* `lifetime`: The coupon will be applied forever.
example: limited
frequencyInterval:
description: >-
The number of billing periods the coupon will be applied for.
**Required for frequency `limited`.**
example: 3
type:
- integer
- 'null'
TierItem:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
type: string
from:
description: The lower bound of the tier
type: number
amount:
description: The amount of the tier per unit
type: number
flatAmount:
description: >-
The flat amount of the tier, billed once in addition to the amount
per unit in a billing period
type: number
createdAt:
readOnly: true
description: The date and time when the resource was created.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
updatedAt:
readOnly: true
description: The date and time when the resource was last updated.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
tenantId:
readOnly: true
type: string
required:
- from
- amount
- flatAmount
Unit-SubscriptionDetail:
type: object
description: ''
deprecated: false
properties:
id:
$ref: '#/components/schemas/UnitId-SubscriptionDetail'
readOnly: true
name:
example: Stück
type: string
createdAt:
readOnly: true
description: The date and time when the resource was created.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
updatedAt:
readOnly: true
description: The date and time when the resource was last updated.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
MoneyEmbeddedDefaultNull-SubscriptionDetail:
type: object
description: ''
deprecated: false
UnitId-SubscriptionDetail:
type: object
description: ''
deprecated: false
securitySchemes:
JWT:
type: http
scheme: bearer
````