> ## 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.
# Create a coupon
> You can create a coupon, which can be used by customers to get a discount on their subscription.
You can create a coupon with a *fixed amount* or a *percentage*. You can also set a maximum number of uses and a maximum number of uses per customer.
You can also set an end date, after which the coupon is no longer valid.
The coupon code can be used in the checkout process, in the customer front, or via the API.
Required permissions: `coupon:write`
## OpenAPI
````yaml post /coupons
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:
/coupons:
parameters: []
post:
tags:
- Coupon
summary: Create a coupon
description: >-
You can create a coupon, which can be used by customers to get a
discount on their subscription.
You can create a coupon with a *fixed amount* or a *percentage*. You can
also set a maximum number of uses and a maximum number of uses per
customer.
You can also set an end date, after which the coupon is no longer valid.
The coupon code can be used in the checkout process, in the customer
front, or via the API.
Required permissions: `coupon:write`
operationId: createCoupon
parameters: []
requestBody:
description: The new Coupon resource
content:
application/json:
schema:
$ref: '#/components/schemas/Coupon-CouponWrite'
text/html:
schema:
$ref: '#/components/schemas/Coupon-CouponWrite'
required: true
responses:
'201':
description: Coupon resource created
content:
application/json:
schema:
$ref: '#/components/schemas/Coupon-CouponDetail'
text/html:
schema:
$ref: '#/components/schemas/Coupon-CouponDetail'
links: {}
'400':
description: Invalid input
'422':
description: Unprocessable entity
deprecated: false
security:
- JWT:
- coupon:write
x-codeSamples:
- lang: bash
label: cURL
source: |-
curl -X POST \
/coupons \
--header "Content-Type: application/json" \
--header "Authorization: Bearer " \
--data '{
"code": "10OFF",
"name": "10% off",
"percentage": "10",
"fixedAmount": [],
"frequencyInterval": "3",
"maxRedemptionsPerCustomer": "null",
"maxRedemptions": "null",
"expiresAt": "null",
"limitedToPlans": [
"https:\/\/example.com\/"
],
"excludedFromPlans": [
"https:\/\/example.com\/"
],
"limitedToProducts": [
"https:\/\/example.com\/"
],
"excludedFromProducts": [
"https:\/\/example.com\/"
],
"isEnabled": "1"
}'
components:
schemas:
Coupon-CouponWrite:
type: object
description: ''
deprecated: false
required:
- code
- name
- type
- frequency
properties:
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-CouponWrite'
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'
maxRedemptionsPerCustomer:
description: >-
The number of times this coupon can be redeemed by a customer. If
null, there is no limit.
default: 'null'
example: 'null'
type:
- integer
- 'null'
maxRedemptions:
description: >-
The number of times this coupon can be redeemed in total. If null,
there is no limit.
default: 'null'
example: 'null'
type:
- integer
- 'null'
expiresAt:
description: >-
The date and time this coupon will expire. If null, there is no
expiration date.
default: 'null'
example: 'null'
type:
- string
- 'null'
format: date-time
limitedToPlans:
description: The plans this coupon should be applied to.
type: array
items:
type: string
format: uuid
example: https://example.com/
excludedFromPlans:
description: The plans this coupon should not be applied to.
type: array
items:
type: string
format: uuid
example: https://example.com/
limitedToProducts:
description: The products this coupon should be applied to.
type: array
items:
type: string
format: uuid
example: https://example.com/
excludedFromProducts:
description: The products this coupon should not be applied to.
type: array
items:
type: string
format: uuid
example: https://example.com/
isEnabled:
description: Whether this coupon is enabled or not.
default: true
example: true
type: boolean
Coupon-CouponDetail:
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-CouponDetail'
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'
maxRedemptionsPerCustomer:
description: >-
The number of times this coupon can be redeemed by a customer. If
null, there is no limit.
default: 'null'
example: 'null'
type:
- integer
- 'null'
maxRedemptions:
description: >-
The number of times this coupon can be redeemed in total. If null,
there is no limit.
default: 'null'
example: 'null'
type:
- integer
- 'null'
expiresAt:
description: >-
The date and time this coupon will expire. If null, there is no
expiration date.
default: 'null'
example: 'null'
type:
- string
- 'null'
format: date-time
limitedToPlans:
description: The plans this coupon should be applied to.
type: array
items:
$ref: '#/components/schemas/Plan-CouponDetail'
excludedFromPlans:
description: The plans this coupon should not be applied to.
type: array
items:
$ref: '#/components/schemas/Plan-CouponDetail'
limitedToProducts:
description: The products this coupon should be applied to.
type: array
items:
$ref: '#/components/schemas/Product-CouponDetail'
excludedFromProducts:
description: The products this coupon should not be applied to.
type: array
items:
$ref: '#/components/schemas/Product-CouponDetail'
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
reedemptions:
readOnly: true
description: >-
Has this coupon been redeemed by a customer? If yes, it cannot be
edited or deleted anymore.
type: boolean
required:
- code
- name
- type
- frequency
MoneyEmbeddedDefaultNull-CouponWrite:
type: object
description: ''
deprecated: false
MoneyEmbeddedDefaultNull-CouponDetail:
type: object
description: ''
deprecated: false
Plan-CouponDetail:
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-CouponDetail'
- 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-CouponDetail'
- 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
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'
Product-CouponDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
description: The unique identifier of the product.
example: ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b
type: string
productFamilies:
description: A product family groups multiple products together.
type: array
items:
$ref: '#/components/schemas/ProductFamily-CouponDetail'
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'
number:
minLength: 2
maxLength: 255
description: Internal product number
example: M-1234
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-CouponDetail'
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-CouponDetail'
- type: 'null'
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
taxGroup:
$ref: '#/components/schemas/TaxGroup-CouponDetail'
description: The tax group that is used for the product.
isArchived:
description: Defines if the product is archived and should not be used anymore.
type: boolean
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:
- productFamilies
- type
- measurement
- taxGroup
PlanFamily-CouponDetail:
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
ProductFamily-CouponDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
example: ad8b3b9e-5b0a-4e1a-8b0a-4e1a8b0a4e1a
type: string
name:
maxLength: 255
example: Team Packages
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:
- name
Measurement-CouponDetail:
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-CouponDetail'
- 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-CouponDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
example: ad8f1c9c-4f0a-4e1a-8b1a-9c4d9c4d9c4d
type: string
name:
maxLength: 255
description: The name of the cost centre, which is displayed in the UI
example: Cost Centre
type: string
code:
description: The code of the cost centre, which is used for exports
example: CC
type: string
type:
description: The type of the cost centre, which is used for exports
example: KOST1
type: string
enum:
- KOST1
- KOST2
createdAt:
readOnly: true
description: The date and time when the cost centre 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 cost centre was last updated
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
required:
- name
- type
TaxGroup-CouponDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
example: 00000000-0000-0000-0000-000000000000
type: string
internalDescription:
maxLength: 255
description: The name of the tax group which will be displayed only in the UI
example: 19%
type: string
reverseChargeType:
description: Defines if reverse charge will be applicated or not
default: REVERSE_CHARGE
example: REVERSE_CHARGE
enum:
- REVERSE_CHARGE_DEACTIVATED
- REVERSE_CHARGE
- REVERSE_CHARGE_INTRA_EU_SUPPLY
type:
default: standard
example: standard
enum:
- standard
- reduced
required:
- internalDescription
- reverseChargeType
- type
Unit-CouponDetail:
type: object
description: ''
deprecated: false
properties:
id:
$ref: '#/components/schemas/UnitId-CouponDetail'
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-CouponDetail:
type: object
description: ''
deprecated: false
securitySchemes:
JWT:
type: http
scheme: bearer
````