> ## 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.
# Get a product
> Get a product
Required permissions: `product:read`
## OpenAPI
````yaml get /catalogue/products/{id}
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:
/catalogue/products/{id}:
parameters: []
get:
tags:
- Product
summary: Get a product
description: |-
Get a product
Required permissions: `product:read`
operationId: api_catalogueproducts_id_get
parameters:
- name: id
in: path
description: Product identifier
required: true
deprecated: false
schema:
type: string
style: simple
explode: false
responses:
'200':
description: Product resource
content:
application/json:
schema:
$ref: '#/components/schemas/Product-ProductDetail'
text/html:
schema:
$ref: '#/components/schemas/Product-ProductDetail'
'404':
description: Resource not found
deprecated: false
security:
- JWT:
- product:read
x-codeSamples:
- lang: bash
label: cURL
source: |-
curl -X GET \
/catalogue/products/{id} \
--header "Authorization: Bearer "
components:
schemas:
Product-ProductDetail:
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-ProductDetail'
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'
translations:
minItems: 1
description: The translations of the product. The locale is used as key.
type: object
additionalProperties:
$ref: '#/components/schemas/ProductTranslation-ProductDetail'
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-ProductDetail'
description: >-
The measurement that is used for the price plan. This could define
the quantity or a metered usage.
pricePlans:
description: >-
The price plans of the product. Describes multiple prices which
could be selled by this product.
type: array
items:
$ref: '#/components/schemas/PricePlan-ProductDetail'
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-ProductDetail'
- type: 'null'
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
taxGroup:
$ref: '#/components/schemas/TaxGroup-ProductDetail'
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
- translations
- type
- measurement
- taxGroup
ProductFamily-ProductDetail:
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
required:
- name
ProductTranslation-ProductDetail:
type: object
description: ''
deprecated: false
properties:
locale:
minLength: 2
maxLength: 2
example: en
type: string
name:
minLength: 2
maxLength: 255
example: Basic
type: string
description:
maxLength: 10000
example: For small teams
type:
- string
- 'null'
required:
- name
Measurement-ProductDetail:
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-ProductDetail'
- 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
PricePlan-ProductDetail:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
description: The unique identifier of the price plan.
example: ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b
type: string
internalName:
minLength: 3
maxLength: 255
description: The internal name of the price plan.
example: Exclusive pricing for partners.
type:
- string
- 'null'
status:
readOnly: true
description: |-
The status of the price plan.
Possible values:
* `active`: The price is active and can be used.
* `archived`: The price is archived and cannot be used anymore. It will be not shown in any lists until explicitly requested.
default: active
example: active
salesChannel:
description: >-
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.
anyOf:
- $ref: '#/components/schemas/SalesChannel-ProductDetail'
- type: 'null'
type:
description: |-
The type of the charge. This defines how the price is calculated.
Possible values:
* `flat_fee`: A flat fee is charged, e.g. 10€ per month independent of the number of units.
* `volume`: A volume based price is charged, e.g. 10€ for the first 10 units and 9€ for all units when the number of units is above 10. Useful for volume discounts.
* `percentage`: A percentage of the total price is charged, e.g. 10% of the total price multiplied by the number of units. Useful for provisions.
* `per_unit`: A price per unit is charged, e.g. 10€ per unit per billing interval. Useful for per seat based pricing.
* `tiered`: A tiered price is charged. E.g. 10€ per unit for the first 10 units, 9€ per unit for the next 10 units and 8€ per unit for all units above 20.
* `stair_step`: A stair step price is charged. E.g. 10€ per unit for the first 10 units, 9€ per unit for all units above 10.
example: flat_fee
applyTrial:
description: >-
If this is set to true, the price plan can be applied on a trial. If
the product is in trial, and this is false, the price will be
charged on subscription start, otherwise after trial.
default: true
example: true
type: boolean
payInAdvance:
description: >-
If this is set to true, the price will be charged in advance. If
this is false, the price will be charged at the end of the billing
interval.
default: true
example: true
type:
- boolean
- 'null'
proRata:
description: >-
If this is set to true, the price will be charged prorated when a
partial billing interval is billed. This applies to measurements of
type "recurring" or non-one-time billing intervals. For other
measurements this parameter will be ignored.
type: boolean
freeUnits:
description: >-
The amount of free units. If null, no free units are available. Free
units will be applied before passed to the price calculation and are
available prorated.
If the customer does not uses the free units during a billing
period, they are not carried over to the next billing period.
If the customer cancels the subscription before ending the billing
period, the free units are only available prorated for the remaining
billing period.
**Example**: You offer 2400 free units for 12 months and your price
has a billing interval for 1 month. The customer cancels after 6
months. Only 1200 free units are available.
**A price plan for a recurring product cannot have free units. Use a
metered product instead.**
**A price plan related to a product of type charge cannot have free
units.**
anyOf:
- $ref: '#/components/schemas/Quantity-ProductDetail'
- type: 'null'
billingInterval:
description: >-
The billing interval of the price plan. If null, this is a one-time
charge.
Billing intervals of null cannot be prorated.
example: 1M
anyOf:
- $ref: '#/components/schemas/BillingInterval-ProductDetail'
- type: 'null'
showPricePerInterval:
description: >-
Display the billed price per interval in customerfront or invoices.
If null, the price will be shown per billing interval.
Currently only available for billing intervals of months, years.
Currently only allowed to show price per month (1M)
example: 1M
anyOf:
- $ref: '#/components/schemas/Interval-ProductDetail'
- type: 'null'
currencyCode:
$ref: '#/components/schemas/CurrencyCode-ProductDetail'
description: The currency of the price
price:
description: The price in the defined billing interval.
type: object
oneOf:
- $ref: '#/components/schemas/FlatFeePrice'
title: Flat fee
- $ref: '#/components/schemas/PercentagePrice'
title: Percentage
- $ref: '#/components/schemas/PerUnitPrice'
title: Per unit
- $ref: '#/components/schemas/TieredPrice'
title: Tiered
custom:
readOnly: true
description: >-
If this price plan is a custom price plan. A price plan is custom if
it is defined specific for a plan addon, plan charge, customer or
sales channel.
example: true
type: boolean
charge:
description: The charge related to this price plan.
example: ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b
type: string
format: uuid
productSetOption:
description: The product set option related to this price plan.
example: ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b
type: string
format: uuid
product:
readOnly: true
description: The product this price plan belongs to.
nullable: false
customer:
readOnly: true
description: The customer this price plan belongs to.
nullable: false
inUse:
readOnly: true
description: If this price plan is in use.
example: true
type: boolean
checkoutLinkIds:
readOnly: true
description: The checkout link IDs related to this price plan.
example:
- ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b
type: array
items:
type: string
required:
- type
- currencyCode
- price
CostCentre-ProductDetail:
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-ProductDetail:
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-ProductDetail:
type: object
description: ''
deprecated: false
properties:
id:
$ref: '#/components/schemas/UnitId-ProductDetail'
readOnly: true
name:
example: Stück
type: string
translations:
type: object
additionalProperties:
$ref: '#/components/schemas/UnitTranslation-ProductDetail'
SalesChannel-ProductDetail:
type: object
description: Der Vertriebskanal (kompakte Referenz).
deprecated: false
properties:
id:
readOnly: true
type: string
name:
readOnly: true
type: string
description: Stabiler technischer Name des Kanals (z. B. "default").
brandName:
readOnly: true
type: string
description: Anzeigename der Marke.
Quantity-ProductDetail:
type:
- number
- 'null'
description: A numeric quantity value.
example: 1
BillingInterval-ProductDetail:
type: object
description: ''
deprecated: false
Interval-ProductDetail:
type: object
description: ''
deprecated: false
CurrencyCode-ProductDetail:
type: string
description: ISO 4217 currency code.
example: EUR
FlatFeePrice:
type: object
description: ''
deprecated: false
required:
- amount
properties:
amount:
description: The amount of the flat fee per unit
type: number
createdAt:
readOnly: true
description: The date and time when the resource was created.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
updatedAt:
readOnly: true
description: The date and time when the resource was last updated.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
tenantId:
readOnly: true
type: string
title: Flat fee
PercentagePrice:
type: object
description: ''
deprecated: false
required:
- percentage
- fixedAmount
- freeUnitsPerEvent
- freeUnitsPerBillingInterval
properties:
percentage:
description: The percentage of the total amount that is charged.
type: number
fixedAmount:
description: >-
The fixed amount that is charged per unit, metered in the billing
period. E.g. on pushing 1000 units, the fixed amount is charged 1000
times * percentage
type: number
freeUnitsPerEvent:
description: The number of units that are not subject to the fixed fee.
type: integer
freeUnitsPerBillingInterval:
description: The amount that is not subject to the charge rate.
type: number
createdAt:
readOnly: true
description: The date and time when the resource was created.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
updatedAt:
readOnly: true
description: The date and time when the resource was last updated.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
tenantId:
readOnly: true
type: string
title: Percentage
PerUnitPrice:
type: object
description: ''
deprecated: false
required:
- amount
properties:
amount:
description: The amount of money per unit
example: 0.99
type: number
createdAt:
readOnly: true
description: The date and time when the resource was created.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
updatedAt:
readOnly: true
description: The date and time when the resource was last updated.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
tenantId:
readOnly: true
type: string
title: Per unit
TieredPrice:
type: object
description: ''
deprecated: false
required:
- items
properties:
items:
minItems: 1
type: array
items:
$ref: '#/components/schemas/TierItem'
createdAt:
readOnly: true
description: The date and time when the resource was created.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
updatedAt:
readOnly: true
description: The date and time when the resource was last updated.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
tenantId:
readOnly: true
type: string
title: Tiered
UnitId-ProductDetail:
type: object
description: ''
deprecated: false
UnitTranslation-ProductDetail:
type: object
description: ''
deprecated: false
required:
- name
- locale
properties:
name:
maxLength: 255
example: Stück
type: string
locale:
example: de
type: string
TierItem:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
type: string
from:
description: The lower bound of the tier
type: number
amount:
description: The amount of the tier per unit
type: number
flatAmount:
description: >-
The flat amount of the tier, billed once in addition to the amount
per unit in a billing period
type: number
createdAt:
readOnly: true
description: The date and time when the resource was created.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
updatedAt:
readOnly: true
description: The date and time when the resource was last updated.
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
tenantId:
readOnly: true
type: string
required:
- from
- amount
- flatAmount
securitySchemes:
JWT:
type: http
scheme: bearer
````