API documentation
User
Tenant
Feature
Entitlement
User & permissions
Settings
Payment
Customer
Billing
Dunning
Subscription
Offers
Catalogue
Checkout
curl -X GET \
/catalogue/products/{id} \
--header "Authorization: Bearer <token>"{
"productFamilies": [
{
"name": "Team Packages",
"id": "ad8b3b9e-5b0a-4e1a-8b0a-4e1a8b0a4e1a"
}
],
"translations": {},
"type": "product",
"measurement": {
"unit": {
"id": {},
"name": "Stück",
"translations": {}
},
"code": "users",
"id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
"description": "The number of users.",
"aggregationType": "sum",
"fairBilling": true,
"type": "recurring"
},
"taxGroup": {
"internalDescription": "19%",
"reverseChargeType": "REVERSE_CHARGE",
"type": "standard",
"id": "00000000-0000-0000-0000-000000000000"
},
"id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
"name": "Basic",
"description": "For small teams.",
"internalName": "Basic (Weekly)",
"number": "M-1234",
"pricePlans": [
{
"type": "flat_fee",
"currencyCode": {},
"price": {
"amount": 123,
"createdAt": "2021-01-01T00:00:00+00:00",
"updatedAt": "2021-01-01T00:00:00+00:00",
"tenantId": "<string>"
},
"id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
"internalName": "Exclusive pricing for partners.",
"status": "active",
"salesChannel": {},
"applyTrial": true,
"payInAdvance": true,
"proRata": true,
"freeUnits": {},
"billingInterval": "1M",
"showPricePerInterval": "1M",
"custom": true,
"charge": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
"productSetOption": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
"product": "<unknown>",
"customer": "<unknown>",
"inUse": true,
"checkoutLinkIds": [
"ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"
]
}
],
"invoiceVisibility": "always",
"costCentre": {
"name": "Cost Centre",
"type": "KOST1",
"id": "ad8f1c9c-4f0a-4e1a-8b1a-9c4d9c4d9c4d",
"code": "CC",
"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",
"isArchived": true,
"customFields": {
"field1": "value1",
"field2": "value2"
}
}Get a product
Get a product
Required permissions:product:readcurl -X GET \
/catalogue/products/{id} \
--header "Authorization: Bearer <token>"{
"productFamilies": [
{
"name": "Team Packages",
"id": "ad8b3b9e-5b0a-4e1a-8b0a-4e1a8b0a4e1a"
}
],
"translations": {},
"type": "product",
"measurement": {
"unit": {
"id": {},
"name": "Stück",
"translations": {}
},
"code": "users",
"id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
"description": "The number of users.",
"aggregationType": "sum",
"fairBilling": true,
"type": "recurring"
},
"taxGroup": {
"internalDescription": "19%",
"reverseChargeType": "REVERSE_CHARGE",
"type": "standard",
"id": "00000000-0000-0000-0000-000000000000"
},
"id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
"name": "Basic",
"description": "For small teams.",
"internalName": "Basic (Weekly)",
"number": "M-1234",
"pricePlans": [
{
"type": "flat_fee",
"currencyCode": {},
"price": {
"amount": 123,
"createdAt": "2021-01-01T00:00:00+00:00",
"updatedAt": "2021-01-01T00:00:00+00:00",
"tenantId": "<string>"
},
"id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
"internalName": "Exclusive pricing for partners.",
"status": "active",
"salesChannel": {},
"applyTrial": true,
"payInAdvance": true,
"proRata": true,
"freeUnits": {},
"billingInterval": "1M",
"showPricePerInterval": "1M",
"custom": true,
"charge": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
"productSetOption": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
"product": "<unknown>",
"customer": "<unknown>",
"inUse": true,
"checkoutLinkIds": [
"ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"
]
}
],
"invoiceVisibility": "always",
"costCentre": {
"name": "Cost Centre",
"type": "KOST1",
"id": "ad8f1c9c-4f0a-4e1a-8b1a-9c4d9c4d9c4d",
"code": "CC",
"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",
"isArchived": true,
"customFields": {
"field1": "value1",
"field2": "value2"
}
}Authorizations
Value for the Authorization header parameter.
Path Parameters
Product identifier
Response
Product resource
The translations of the product. The locale is used as key.
Show child attributes
Show child attributes
The type of the product.
product: recurring billed productcharge: one-time billingplan: plan specific product, which cannot be used as a normal product. Will be filtered out in any product lists.
product, charge, plan The measurement that is used for the price plan. This could define the quantity or a metered usage.
Show child attributes
Show child attributes
The unit of the measurement.
Show child attributes
Show child attributes
"Stück"
A unique code which can be used to identify the measurement.
1 - 255"users"
A unique identifier for the measurement.
"ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"
A description of the measurement, which is shown in the summary of the usage data in the invoice.
255"The number of users."
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.
"sum"
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.
true
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".
"recurring"
The tax group that is used for the product.
Show child attributes
Show child attributes
The name of the tax group which will be displayed only in the UI
255"19%"
Defines if reverse charge will be applicated or not
REVERSE_CHARGE_DEACTIVATED, REVERSE_CHARGE, REVERSE_CHARGE_INTRA_EU_SUPPLY "REVERSE_CHARGE"
standard, reduced "standard"
"00000000-0000-0000-0000-000000000000"
The unique identifier of the product.
"ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"
The name of the product based on the current tenant language. This will be displayed on customer communication.
"Basic"
The description of the product based on the current tenant language.
"For small teams."
Internal name of the product, to differentiate between products with the same name. This will shown in web-app lists, selections and reports.
"Basic (Weekly)"
Internal product number
2 - 255"M-1234"
The price plans of the product. Describes multiple prices which could be selled by this product.
Show child attributes
Show child attributes
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.
"flat_fee"
The currency of the price
The price in the defined billing interval.
- Flat fee
- Percentage
- Per unit
- Tiered
Show child attributes
Show child attributes
The amount of the flat fee per unit
The date and time when the resource was created.
"2021-01-01T00:00:00+00:00"
The date and time when the resource was last updated.
"2021-01-01T00:00:00+00:00"
The unique identifier of the price plan.
"ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"
The internal name of the price plan.
3 - 255"Exclusive pricing for partners."
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.
"active"
This price is only available for a specific sales channel. If this is set, the price is only available for the sales channel with the given ID. All other price plans will be ignored.
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.
true
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.
true
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.
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.
The billing interval of the price plan. If null, this is a one-time charge. Billing intervals of null cannot be prorated.
"1M"
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)
"1M"
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.
true
The charge related to this price plan.
"ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"
The product set option related to this price plan.
"ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"
The product this price plan belongs to.
The customer this price plan belongs to.
If this price plan is in use.
true
The checkout link IDs related to this price plan.
["ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"]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.
always, only_if_charged The cost centre is used for accounting exports.
Show child attributes
Show child attributes
The name of the cost centre, which is displayed in the UI
255"Cost Centre"
The type of the cost centre, which is used for exports
KOST1, KOST2 "KOST1"
"ad8f1c9c-4f0a-4e1a-8b1a-9c4d9c4d9c4d"
The code of the cost centre, which is used for exports
"CC"
The date and time when the cost centre was created
"2021-01-01T00:00:00+00:00"
The date and time when the cost centre was last updated
"2021-01-01T00:00:00+00:00"
Defines if the product is archived and should not be used anymore.
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
Show child attributes
Show child attributes
{ "field1": "value1", "field2": "value2" }Was this page helpful?