> ## 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.
# Cancel subscription
> Cancel the subscription. This will stop billing and the subscription will be inactive after the cancellation date.
Required permissions: `subscription:write`
## OpenAPI
````yaml put /subscriptions/{id}/cancel
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}/cancel:
parameters: []
put:
tags:
- Subscription
summary: Cancel subscription
description: >-
Cancel the subscription. This will stop billing and the subscription
will be inactive after the cancellation date.
Required permissions: `subscription:write`
operationId: api_subscriptions_idcancel_put
parameters:
- name: id
in: path
description: Subscription identifier
required: true
deprecated: false
schema:
type: string
style: simple
explode: false
requestBody:
description: The updated Subscription resource
content:
application/json:
schema:
$ref: >-
#/components/schemas/Subscription.CancelSubscription-CancelSubscription
text/html:
schema:
$ref: >-
#/components/schemas/Subscription.CancelSubscription-CancelSubscription
required: true
responses:
'200':
description: Subscription resource updated
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription-SubscriptionRead'
text/html:
schema:
$ref: '#/components/schemas/Subscription-SubscriptionRead'
links: {}
'400':
description: Invalid input
'404':
description: Resource not found
'422':
description: Unprocessable entity
deprecated: false
security:
- JWT:
- subscription:write
x-codeSamples:
- lang: bash
label: cURL
source: |-
curl -X PUT \
/subscriptions/{id}/cancel \
--header "Content-Type: application/json" \
--header "Authorization: Bearer " \
--data '{
"cancellationDateType": "next_possible",
"cancellationDate": "2022-12-31",
"sendConfirmationEmail": "1",
"reason": ""
}'
components:
schemas:
Subscription.CancelSubscription-CancelSubscription:
type: object
description: ''
deprecated: false
properties:
cancellationDateType:
description: The type how the cancellation date should be interpreted.
example: next_possible
type: string
enum:
- immediate
- next_possible
- custom
cancellationDate:
description: >-
The date when the subscription should be cancelled. Required if the
type is `custom`.
example: '2022-12-31'
type:
- string
- 'null'
format: date-time
sendConfirmationEmail:
description: If the confirmation email should be sent to the customer.
example: true
type: boolean
reason:
description: The reason code why the subscription should be cancelled.
type:
- string
- 'null'
Subscription-SubscriptionRead:
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-SubscriptionRead'
- 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-SubscriptionRead'
- type: 'null'
number:
description: The number of the subscription.
example: S-00000001
type: string
customer:
$ref: '#/components/schemas/Customer-SubscriptionRead'
plan:
readOnly: true
description: The plan this subscription is based on.
anyOf:
- $ref: '#/components/schemas/Plan-SubscriptionRead'
- 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'
billingGroup:
description: The billing group defines the billing cycle of the subscription.
anyOf:
- $ref: '#/components/schemas/BillingGroup-SubscriptionRead'
- type: 'null'
periods:
type: array
items:
$ref: '#/components/schemas/TermPeriod-SubscriptionRead'
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-SubscriptionRead'
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
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-SubscriptionRead'
- type: 'null'
PaymentMethod-SubscriptionRead:
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-SubscriptionRead:
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-SubscriptionRead:
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-SubscriptionRead:
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-SubscriptionRead'
- 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-SubscriptionRead'
- 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'
BillingGroup-SubscriptionRead:
type: object
description: ''
deprecated: false
TermPeriod-SubscriptionRead:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
type: string
contractPeriodCount:
readOnly: true
type: integer
contractPeriod:
$ref: '#/components/schemas/Interval-SubscriptionRead'
readOnly: true
cancellationPeriod:
$ref: '#/components/schemas/Interval-SubscriptionRead'
readOnly: true
createdAt:
readOnly: true
type: string
format: date-time
updatedAt:
readOnly: true
type: string
format: date-time
ContractDetails-SubscriptionRead:
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
PartnerResource-SubscriptionRead:
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'
PlanFamily-SubscriptionRead:
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-SubscriptionRead:
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-SubscriptionRead'
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-SubscriptionRead'
- type: 'null'
taxGroup:
$ref: '#/components/schemas/TaxGroup-SubscriptionRead'
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
Interval-SubscriptionRead:
type: object
description: ''
deprecated: false
Measurement-SubscriptionRead:
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-SubscriptionRead'
- 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-SubscriptionRead:
type: object
description: ''
deprecated: false
TaxGroup-SubscriptionRead:
type: object
description: ''
deprecated: false
Unit-SubscriptionRead:
type: object
description: ''
deprecated: false
properties:
id:
$ref: '#/components/schemas/UnitId-SubscriptionRead'
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
UnitId-SubscriptionRead:
type: object
description: ''
deprecated: false
securitySchemes:
JWT:
type: http
scheme: bearer
````