Create a coupon

POST

coupons

curl -X POST \
 /coupons \
 --header "Content-Type: application/json" \
 --header "Authorization: Bearer <token>" \
 --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"
}'

{
  "id": "<string>",
  "code": "10OFF",
  "name": "10% off",
  "type": "<any>",
  "percentage": 10,
  "fixedAmount": {},
  "frequency": "<any>",
  "frequencyInterval": 3,
  "maxRedemptionsPerCustomer": "null",
  "maxRedemptions": "null",
  "expiresAt": "null",
  "limitedToPlans": [
    {
      "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "family": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "createdAt": "2021-01-01T00:00:00+00:00",
        "updatedAt": "2021-01-01T00:00:00+00:00"
      },
      "code": "basic-m2023",
      "originProduct": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "productFamilies": [
          {
            "id": "ad8b3b9e-5b0a-4e1a-8b0a-4e1a8b0a4e1a",
            "name": "Team Packages",
            "createdAt": "2021-01-01T00:00:00+00:00",
            "updatedAt": "2021-01-01T00:00:00+00:00"
          }
        ],
        "name": "Basic",
        "description": "For small teams.",
        "internalName": "Basic (Weekly)",
        "number": "M-1234",
        "type": "product",
        "measurement": {
          "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
          "unit": {
            "id": {},
            "name": "Stück",
            "createdAt": "2021-01-01T00:00:00+00:00",
            "updatedAt": "2021-01-01T00:00:00+00:00"
          },
          "code": "users",
          "description": "The number of users.",
          "aggregationType": "<any>",
          "fairBilling": true,
          "type": "<any>"
        },
        "invoiceVisibility": "always",
        "costCentre": {
          "id": "ad8f1c9c-4f0a-4e1a-8b1a-9c4d9c4d9c4d",
          "name": "Cost Centre",
          "code": "CC",
          "type": "KOST1",
          "createdAt": "2021-01-01T00:00:00+00:00",
          "updatedAt": "2021-01-01T00:00:00+00:00"
        },
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "taxGroup": {
          "id": "00000000-0000-0000-0000-000000000000",
          "internalDescription": "19%",
          "reverseChargeType": "REVERSE_CHARGE",
          "type": "standard"
        },
        "isArchived": true,
        "customFields": {
          "field1": "value1",
          "field2": "value2"
        }
      },
      "allowCheckout": true,
      "status": "<any>",
      "createdAt": "2023-11-07T05:31:56Z",
      "name": "<string>",
      "description": "<string>"
    }
  ],
  "excludedFromPlans": [
    {
      "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "family": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "createdAt": "2021-01-01T00:00:00+00:00",
        "updatedAt": "2021-01-01T00:00:00+00:00"
      },
      "code": "basic-m2023",
      "originProduct": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "productFamilies": [
          {
            "id": "ad8b3b9e-5b0a-4e1a-8b0a-4e1a8b0a4e1a",
            "name": "Team Packages",
            "createdAt": "2021-01-01T00:00:00+00:00",
            "updatedAt": "2021-01-01T00:00:00+00:00"
          }
        ],
        "name": "Basic",
        "description": "For small teams.",
        "internalName": "Basic (Weekly)",
        "number": "M-1234",
        "type": "product",
        "measurement": {
          "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
          "unit": {
            "id": {},
            "name": "Stück",
            "createdAt": "2021-01-01T00:00:00+00:00",
            "updatedAt": "2021-01-01T00:00:00+00:00"
          },
          "code": "users",
          "description": "The number of users.",
          "aggregationType": "<any>",
          "fairBilling": true,
          "type": "<any>"
        },
        "invoiceVisibility": "always",
        "costCentre": {
          "id": "ad8f1c9c-4f0a-4e1a-8b1a-9c4d9c4d9c4d",
          "name": "Cost Centre",
          "code": "CC",
          "type": "KOST1",
          "createdAt": "2021-01-01T00:00:00+00:00",
          "updatedAt": "2021-01-01T00:00:00+00:00"
        },
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "taxGroup": {
          "id": "00000000-0000-0000-0000-000000000000",
          "internalDescription": "19%",
          "reverseChargeType": "REVERSE_CHARGE",
          "type": "standard"
        },
        "isArchived": true,
        "customFields": {
          "field1": "value1",
          "field2": "value2"
        }
      },
      "allowCheckout": true,
      "status": "<any>",
      "createdAt": "2023-11-07T05:31:56Z",
      "name": "<string>",
      "description": "<string>"
    }
  ],
  "limitedToProducts": [
    {
      "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "productFamilies": [
        {
          "id": "ad8b3b9e-5b0a-4e1a-8b0a-4e1a8b0a4e1a",
          "name": "Team Packages",
          "createdAt": "2021-01-01T00:00:00+00:00",
          "updatedAt": "2021-01-01T00:00:00+00:00"
        }
      ],
      "name": "Basic",
      "description": "For small teams.",
      "internalName": "Basic (Weekly)",
      "number": "M-1234",
      "type": "product",
      "measurement": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "unit": {
          "id": {},
          "name": "Stück",
          "createdAt": "2021-01-01T00:00:00+00:00",
          "updatedAt": "2021-01-01T00:00:00+00:00"
        },
        "code": "users",
        "description": "The number of users.",
        "aggregationType": "<any>",
        "fairBilling": true,
        "type": "<any>"
      },
      "invoiceVisibility": "always",
      "costCentre": {
        "id": "ad8f1c9c-4f0a-4e1a-8b1a-9c4d9c4d9c4d",
        "name": "Cost Centre",
        "code": "CC",
        "type": "KOST1",
        "createdAt": "2021-01-01T00:00:00+00:00",
        "updatedAt": "2021-01-01T00:00:00+00:00"
      },
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "taxGroup": {
        "id": "00000000-0000-0000-0000-000000000000",
        "internalDescription": "19%",
        "reverseChargeType": "REVERSE_CHARGE",
        "type": "standard"
      },
      "isArchived": true,
      "customFields": {
        "field1": "value1",
        "field2": "value2"
      }
    }
  ],
  "excludedFromProducts": [
    {
      "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "productFamilies": [
        {
          "id": "ad8b3b9e-5b0a-4e1a-8b0a-4e1a8b0a4e1a",
          "name": "Team Packages",
          "createdAt": "2021-01-01T00:00:00+00:00",
          "updatedAt": "2021-01-01T00:00:00+00:00"
        }
      ],
      "name": "Basic",
      "description": "For small teams.",
      "internalName": "Basic (Weekly)",
      "number": "M-1234",
      "type": "product",
      "measurement": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "unit": {
          "id": {},
          "name": "Stück",
          "createdAt": "2021-01-01T00:00:00+00:00",
          "updatedAt": "2021-01-01T00:00:00+00:00"
        },
        "code": "users",
        "description": "The number of users.",
        "aggregationType": "<any>",
        "fairBilling": true,
        "type": "<any>"
      },
      "invoiceVisibility": "always",
      "costCentre": {
        "id": "ad8f1c9c-4f0a-4e1a-8b1a-9c4d9c4d9c4d",
        "name": "Cost Centre",
        "code": "CC",
        "type": "KOST1",
        "createdAt": "2021-01-01T00:00:00+00:00",
        "updatedAt": "2021-01-01T00:00:00+00:00"
      },
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "taxGroup": {
        "id": "00000000-0000-0000-0000-000000000000",
        "internalDescription": "19%",
        "reverseChargeType": "REVERSE_CHARGE",
        "type": "standard"
      },
      "isArchived": true,
      "customFields": {
        "field1": "value1",
        "field2": "value2"
      }
    }
  ],
  "isEnabled": true,
  "createdAt": "2021-01-01T00:00:00+00:00",
  "updatedAt": "2021-01-01T00:00:00+00:00",
  "reedemptions": true
}

Authorizations

Authorization

string

header

required

Value for the Authorization header parameter.

Body

The new Coupon resource

code

string

required

The code that can be used to apply this coupon or to use it with the api.

Example:

"10OFF"

name

string

required

The name of this coupon, which will be displayed to the user in the checkout process, customer front, etc.

Example:

"10% off"

type

any

required

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.

frequency

any

required

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.

percentage

integer | null

The percentage this coupon should apply. Required for type percentage.

Required range: 0 <= x <= 100

Example:

10

fixedAmount

object

The fixed amount this coupon should apply. Required for type fixed_amount.

frequencyInterval

integer | null

The number of billing periods the coupon will be applied for. Required for frequency limited.

Example:

3

maxRedemptionsPerCustomer

integer | null

default:null

The number of times this coupon can be redeemed by a customer. If null, there is no limit.

Example:

null

maxRedemptions

integer | null

default:null

The number of times this coupon can be redeemed in total. If null, there is no limit.

Example:

null

expiresAt

string | null

default:null

The date and time this coupon will expire. If null, there is no expiration date.

Example:

null

limitedToPlans

string[]

The plans this coupon should be applied to.

excludedFromPlans

string[]

The plans this coupon should not be applied to.

limitedToProducts

string[]

The products this coupon should be applied to.

excludedFromProducts

string[]

The products this coupon should not be applied to.

isEnabled

boolean

default:true

Whether this coupon is enabled or not.

Example:

true

Response

201

application/json

Coupon resource created

code

string

required

The code that can be used to apply this coupon or to use it with the api.

Example:

"10OFF"

name

string

required

The name of this coupon, which will be displayed to the user in the checkout process, customer front, etc.

Example:

"10% off"

type

any

required

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.

frequency

any

required

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.

string

The id of this coupon.

percentage

integer | null

The percentage this coupon should apply. Required for type percentage.

Required range: 0 <= x <= 100

Example:

10

fixedAmount

object

The fixed amount this coupon should apply. Required for type fixed_amount.

frequencyInterval

integer | null

The number of billing periods the coupon will be applied for. Required for frequency limited.

Example:

3

maxRedemptionsPerCustomer

integer | null

default:null

The number of times this coupon can be redeemed by a customer. If null, there is no limit.

Example:

null

maxRedemptions

integer | null

default:null

The number of times this coupon can be redeemed in total. If null, there is no limit.

Example:

null

expiresAt

string | null

default:null

The date and time this coupon will expire. If null, there is no expiration date.

Example:

null

limitedToPlans

object[]

The plans this coupon should be applied to.

limitedToPlans.id

string

The unique identifier of the plan.

Example:

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

limitedToPlans.family

object | null

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

limitedToPlans.code

string

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

Example:

"basic-m2023"

limitedToPlans.originProduct

object | null

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

limitedToPlans.originProduct.productFamilies

object[]

required

A product family groups multiple products together.

limitedToPlans.originProduct.type

enum<string>

required

The type of the product.

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

Available options:

product,

charge,

plan

limitedToPlans.originProduct.measurement

object

required

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

limitedToPlans.originProduct.measurement.unit

object | null

required

The unit of the measurement.

limitedToPlans.originProduct.measurement.code

string

required

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

Required string length: 1 - 255

Example:

"users"

limitedToPlans.originProduct.measurement.id

string

A unique identifier for the measurement.

Example:

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

limitedToPlans.originProduct.measurement.description

string | null

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

Maximum length: 255

Example:

"The number of users."

limitedToPlans.originProduct.measurement.aggregationType

any

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

Possible values:

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

limitedToPlans.originProduct.measurement.fairBilling

boolean

default:true

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

Example:

true

limitedToPlans.originProduct.measurement.type

any

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

Possible values:

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

limitedToPlans.originProduct.taxGroup

object

required

The tax group that is used for the product.

limitedToPlans.originProduct.id

string

The unique identifier of the product.

Example:

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

limitedToPlans.originProduct.name

string

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

Example:

"Basic"

limitedToPlans.originProduct.description

string | null

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

Example:

"For small teams."

limitedToPlans.originProduct.internalName

string | null

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

Example:

"Basic (Weekly)"

limitedToPlans.originProduct.number

string | null

Internal product number

Required string length: 2 - 255

Example:

"M-1234"

limitedToPlans.originProduct.invoiceVisibility

enum<string>

Defines when the product should be displayed in the invoice.

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

Available options:

always,

only_if_charged

limitedToPlans.originProduct.costCentre

object | null

The cost centre is used for accounting exports.

limitedToPlans.originProduct.createdAt

string

limitedToPlans.originProduct.updatedAt

string

limitedToPlans.originProduct.isArchived

boolean

Defines if the product is archived and should not be used anymore.

limitedToPlans.originProduct.customFields

object | null

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

Example:

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

limitedToPlans.allowCheckout

boolean

default:true

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

Example:

true

limitedToPlans.status

any

The status of the plan.

Possible values:

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

limitedToPlans.createdAt

string

limitedToPlans.name

string

The name of this plan

limitedToPlans.description

string | null

The description of this plan

excludedFromPlans

object[]

The plans this coupon should not be applied to.

excludedFromPlans.id

string

The unique identifier of the plan.

Example:

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

excludedFromPlans.family

object | null

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

excludedFromPlans.code

string

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

Example:

"basic-m2023"

excludedFromPlans.originProduct

object | null

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

excludedFromPlans.originProduct.productFamilies

object[]

required

A product family groups multiple products together.

excludedFromPlans.originProduct.type

enum<string>

required

The type of the product.

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

Available options:

product,

charge,

plan

excludedFromPlans.originProduct.measurement

object

required

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

excludedFromPlans.originProduct.measurement.unit

object | null

required

The unit of the measurement.

excludedFromPlans.originProduct.measurement.code

string

required

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

Required string length: 1 - 255

Example:

"users"

excludedFromPlans.originProduct.measurement.id

string

A unique identifier for the measurement.

Example:

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

excludedFromPlans.originProduct.measurement.description

string | null

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

Maximum length: 255

Example:

"The number of users."

excludedFromPlans.originProduct.measurement.aggregationType

any

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

Possible values:

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

excludedFromPlans.originProduct.measurement.fairBilling

boolean

default:true

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

Example:

true

excludedFromPlans.originProduct.measurement.type

any

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

Possible values:

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

excludedFromPlans.originProduct.taxGroup

object

required

The tax group that is used for the product.

excludedFromPlans.originProduct.id

string

The unique identifier of the product.

Example:

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

excludedFromPlans.originProduct.name

string

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

Example:

"Basic"

excludedFromPlans.originProduct.description

string | null

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

Example:

"For small teams."

excludedFromPlans.originProduct.internalName

string | null

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

Example:

"Basic (Weekly)"

excludedFromPlans.originProduct.number

string | null

Internal product number

Required string length: 2 - 255

Example:

"M-1234"

excludedFromPlans.originProduct.invoiceVisibility

enum<string>

Defines when the product should be displayed in the invoice.

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

Available options:

always,

only_if_charged

excludedFromPlans.originProduct.costCentre

object | null

The cost centre is used for accounting exports.

excludedFromPlans.originProduct.createdAt

string

excludedFromPlans.originProduct.updatedAt

string

excludedFromPlans.originProduct.isArchived

boolean

Defines if the product is archived and should not be used anymore.

excludedFromPlans.originProduct.customFields

object | null

Example:

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

excludedFromPlans.allowCheckout

boolean

default:true

Example:

true

excludedFromPlans.status

any

The status of the plan.

Possible values:

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

excludedFromPlans.createdAt

string

excludedFromPlans.name

string

The name of this plan

excludedFromPlans.description

string | null

The description of this plan

limitedToProducts

object[]

The products this coupon should be applied to.

limitedToProducts.productFamilies

object[]

required

A product family groups multiple products together.

limitedToProducts.type

enum<string>

required

The type of the product.

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

Available options:

product,

charge,

plan

limitedToProducts.measurement

object

required

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

limitedToProducts.measurement.unit

object | null

required

The unit of the measurement.

limitedToProducts.measurement.code

string

required

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

Required string length: 1 - 255

Example:

"users"

limitedToProducts.measurement.id

string

A unique identifier for the measurement.

Example:

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

limitedToProducts.measurement.description

string | null

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

Maximum length: 255

Example:

"The number of users."

limitedToProducts.measurement.aggregationType

any

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

Possible values:

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

limitedToProducts.measurement.fairBilling

boolean

default:true

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

Example:

true

limitedToProducts.measurement.type

any

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

Possible values:

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

limitedToProducts.taxGroup

object

required

The tax group that is used for the product.

limitedToProducts.id

string

The unique identifier of the product.

Example:

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

limitedToProducts.name

string

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

Example:

"Basic"

limitedToProducts.description

string | null

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

Example:

"For small teams."

limitedToProducts.internalName

string | null

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

Example:

"Basic (Weekly)"

limitedToProducts.number

string | null

Internal product number

Required string length: 2 - 255

Example:

"M-1234"

limitedToProducts.invoiceVisibility

enum<string>

Defines when the product should be displayed in the invoice.

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

Available options:

always,

only_if_charged

limitedToProducts.costCentre

object | null

The cost centre is used for accounting exports.

limitedToProducts.createdAt

string

limitedToProducts.updatedAt

string

limitedToProducts.isArchived

boolean

Defines if the product is archived and should not be used anymore.

limitedToProducts.customFields

object | null

Example:

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

excludedFromProducts

object[]

The products this coupon should not be applied to.

excludedFromProducts.productFamilies

object[]

required

A product family groups multiple products together.

excludedFromProducts.type

enum<string>

required

The type of the product.

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

Available options:

product,

charge,

plan

excludedFromProducts.measurement

object

required

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

excludedFromProducts.measurement.unit

object | null

required

The unit of the measurement.

excludedFromProducts.measurement.code

string

required

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

Required string length: 1 - 255

Example:

"users"

excludedFromProducts.measurement.id

string

A unique identifier for the measurement.

Example:

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

excludedFromProducts.measurement.description

string | null

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

Maximum length: 255

Example:

"The number of users."

excludedFromProducts.measurement.aggregationType

any

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

Possible values:

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

excludedFromProducts.measurement.fairBilling

boolean

default:true

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

Example:

true

excludedFromProducts.measurement.type

any

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

Possible values:

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

excludedFromProducts.taxGroup

object

required

The tax group that is used for the product.

excludedFromProducts.id

string

The unique identifier of the product.

Example:

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

excludedFromProducts.name

string

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

Example:

"Basic"

excludedFromProducts.description

string | null

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

Example:

"For small teams."

excludedFromProducts.internalName

string | null

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

Example:

"Basic (Weekly)"

excludedFromProducts.number

string | null

Internal product number

Required string length: 2 - 255

Example:

"M-1234"

excludedFromProducts.invoiceVisibility

enum<string>

Defines when the product should be displayed in the invoice.

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

Available options:

always,

only_if_charged

excludedFromProducts.costCentre

object | null

The cost centre is used for accounting exports.

excludedFromProducts.createdAt

string

excludedFromProducts.updatedAt

string

excludedFromProducts.isArchived

boolean

Defines if the product is archived and should not be used anymore.

excludedFromProducts.customFields

object | null

Example:

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

isEnabled

boolean

default:true

Whether this coupon is enabled or not.

Example:

true

createdAt

string

The date and time when the resource was created.

Example:

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

updatedAt

string

The date and time when the resource was last updated.

Example:

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

reedemptions

boolean

Has this coupon been redeemed by a customer? If yes, it cannot be edited or deleted anymore.

Get all coupons Get all redeemptions for a coupon

curl -X POST \
 /coupons \
 --header "Content-Type: application/json" \
 --header "Authorization: Bearer <token>" \
 --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"
}'

{
  "id": "<string>",
  "code": "10OFF",
  "name": "10% off",
  "type": "<any>",
  "percentage": 10,
  "fixedAmount": {},
  "frequency": "<any>",
  "frequencyInterval": 3,
  "maxRedemptionsPerCustomer": "null",
  "maxRedemptions": "null",
  "expiresAt": "null",
  "limitedToPlans": [
    {
      "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "family": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "createdAt": "2021-01-01T00:00:00+00:00",
        "updatedAt": "2021-01-01T00:00:00+00:00"
      },
      "code": "basic-m2023",
      "originProduct": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "productFamilies": [
          {
            "id": "ad8b3b9e-5b0a-4e1a-8b0a-4e1a8b0a4e1a",
            "name": "Team Packages",
            "createdAt": "2021-01-01T00:00:00+00:00",
            "updatedAt": "2021-01-01T00:00:00+00:00"
          }
        ],
        "name": "Basic",
        "description": "For small teams.",
        "internalName": "Basic (Weekly)",
        "number": "M-1234",
        "type": "product",
        "measurement": {
          "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
          "unit": {
            "id": {},
            "name": "Stück",
            "createdAt": "2021-01-01T00:00:00+00:00",
            "updatedAt": "2021-01-01T00:00:00+00:00"
          },
          "code": "users",
          "description": "The number of users.",
          "aggregationType": "<any>",
          "fairBilling": true,
          "type": "<any>"
        },
        "invoiceVisibility": "always",
        "costCentre": {
          "id": "ad8f1c9c-4f0a-4e1a-8b1a-9c4d9c4d9c4d",
          "name": "Cost Centre",
          "code": "CC",
          "type": "KOST1",
          "createdAt": "2021-01-01T00:00:00+00:00",
          "updatedAt": "2021-01-01T00:00:00+00:00"
        },
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "taxGroup": {
          "id": "00000000-0000-0000-0000-000000000000",
          "internalDescription": "19%",
          "reverseChargeType": "REVERSE_CHARGE",
          "type": "standard"
        },
        "isArchived": true,
        "customFields": {
          "field1": "value1",
          "field2": "value2"
        }
      },
      "allowCheckout": true,
      "status": "<any>",
      "createdAt": "2023-11-07T05:31:56Z",
      "name": "<string>",
      "description": "<string>"
    }
  ],
  "excludedFromPlans": [
    {
      "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "family": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "createdAt": "2021-01-01T00:00:00+00:00",
        "updatedAt": "2021-01-01T00:00:00+00:00"
      },
      "code": "basic-m2023",
      "originProduct": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "productFamilies": [
          {
            "id": "ad8b3b9e-5b0a-4e1a-8b0a-4e1a8b0a4e1a",
            "name": "Team Packages",
            "createdAt": "2021-01-01T00:00:00+00:00",
            "updatedAt": "2021-01-01T00:00:00+00:00"
          }
        ],
        "name": "Basic",
        "description": "For small teams.",
        "internalName": "Basic (Weekly)",
        "number": "M-1234",
        "type": "product",
        "measurement": {
          "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
          "unit": {
            "id": {},
            "name": "Stück",
            "createdAt": "2021-01-01T00:00:00+00:00",
            "updatedAt": "2021-01-01T00:00:00+00:00"
          },
          "code": "users",
          "description": "The number of users.",
          "aggregationType": "<any>",
          "fairBilling": true,
          "type": "<any>"
        },
        "invoiceVisibility": "always",
        "costCentre": {
          "id": "ad8f1c9c-4f0a-4e1a-8b1a-9c4d9c4d9c4d",
          "name": "Cost Centre",
          "code": "CC",
          "type": "KOST1",
          "createdAt": "2021-01-01T00:00:00+00:00",
          "updatedAt": "2021-01-01T00:00:00+00:00"
        },
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "taxGroup": {
          "id": "00000000-0000-0000-0000-000000000000",
          "internalDescription": "19%",
          "reverseChargeType": "REVERSE_CHARGE",
          "type": "standard"
        },
        "isArchived": true,
        "customFields": {
          "field1": "value1",
          "field2": "value2"
        }
      },
      "allowCheckout": true,
      "status": "<any>",
      "createdAt": "2023-11-07T05:31:56Z",
      "name": "<string>",
      "description": "<string>"
    }
  ],
  "limitedToProducts": [
    {
      "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "productFamilies": [
        {
          "id": "ad8b3b9e-5b0a-4e1a-8b0a-4e1a8b0a4e1a",
          "name": "Team Packages",
          "createdAt": "2021-01-01T00:00:00+00:00",
          "updatedAt": "2021-01-01T00:00:00+00:00"
        }
      ],
      "name": "Basic",
      "description": "For small teams.",
      "internalName": "Basic (Weekly)",
      "number": "M-1234",
      "type": "product",
      "measurement": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "unit": {
          "id": {},
          "name": "Stück",
          "createdAt": "2021-01-01T00:00:00+00:00",
          "updatedAt": "2021-01-01T00:00:00+00:00"
        },
        "code": "users",
        "description": "The number of users.",
        "aggregationType": "<any>",
        "fairBilling": true,
        "type": "<any>"
      },
      "invoiceVisibility": "always",
      "costCentre": {
        "id": "ad8f1c9c-4f0a-4e1a-8b1a-9c4d9c4d9c4d",
        "name": "Cost Centre",
        "code": "CC",
        "type": "KOST1",
        "createdAt": "2021-01-01T00:00:00+00:00",
        "updatedAt": "2021-01-01T00:00:00+00:00"
      },
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "taxGroup": {
        "id": "00000000-0000-0000-0000-000000000000",
        "internalDescription": "19%",
        "reverseChargeType": "REVERSE_CHARGE",
        "type": "standard"
      },
      "isArchived": true,
      "customFields": {
        "field1": "value1",
        "field2": "value2"
      }
    }
  ],
  "excludedFromProducts": [
    {
      "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "productFamilies": [
        {
          "id": "ad8b3b9e-5b0a-4e1a-8b0a-4e1a8b0a4e1a",
          "name": "Team Packages",
          "createdAt": "2021-01-01T00:00:00+00:00",
          "updatedAt": "2021-01-01T00:00:00+00:00"
        }
      ],
      "name": "Basic",
      "description": "For small teams.",
      "internalName": "Basic (Weekly)",
      "number": "M-1234",
      "type": "product",
      "measurement": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "unit": {
          "id": {},
          "name": "Stück",
          "createdAt": "2021-01-01T00:00:00+00:00",
          "updatedAt": "2021-01-01T00:00:00+00:00"
        },
        "code": "users",
        "description": "The number of users.",
        "aggregationType": "<any>",
        "fairBilling": true,
        "type": "<any>"
      },
      "invoiceVisibility": "always",
      "costCentre": {
        "id": "ad8f1c9c-4f0a-4e1a-8b1a-9c4d9c4d9c4d",
        "name": "Cost Centre",
        "code": "CC",
        "type": "KOST1",
        "createdAt": "2021-01-01T00:00:00+00:00",
        "updatedAt": "2021-01-01T00:00:00+00:00"
      },
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "taxGroup": {
        "id": "00000000-0000-0000-0000-000000000000",
        "internalDescription": "19%",
        "reverseChargeType": "REVERSE_CHARGE",
        "type": "standard"
      },
      "isArchived": true,
      "customFields": {
        "field1": "value1",
        "field2": "value2"
      }
    }
  ],
  "isEnabled": true,
  "createdAt": "2021-01-01T00:00:00+00:00",
  "updatedAt": "2021-01-01T00:00:00+00:00",
  "reedemptions": true
}

API documentation

User

Tenant

Feature

Entitlement

User & permissions

Settings

Payment

Analytics

Customer

Billing

Dunning

Subscription

Offers

Catalogue

Checkout

Accounting

Taxes

Authorizations

Body

Response