> ## 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 measurement.
> Create a measurement.
Required permissions: `measurement:write`
## OpenAPI
````yaml post /catalogue/measurements
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/measurements:
parameters: []
post:
tags:
- Measurement
summary: Create a measurement.
description: |-
Create a measurement.
Required permissions: `measurement:write`
operationId: createMeasurement
parameters: []
requestBody:
description: The new Measurement resource
content:
application/json:
schema:
$ref: '#/components/schemas/Measurement'
text/html:
schema:
$ref: '#/components/schemas/Measurement'
required: true
responses:
'201':
description: Measurement resource created
content:
application/json:
schema:
$ref: '#/components/schemas/Measurement-Read'
text/html:
schema:
$ref: '#/components/schemas/Measurement-Read'
links: {}
'400':
description: Invalid input
'422':
description: Unprocessable entity
deprecated: false
security:
- JWT:
- measurement:write
x-codeSamples:
- lang: bash
label: cURL
source: |-
curl -X POST \
/catalogue/measurements \
--header "Content-Type: application/json" \
--header "Authorization: Bearer " \
--data '{
"id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
"unit": "https:\/\/example.com\/",
"code": "users",
"description": "The number of users.",
"fairBilling": "1",
"metered": "",
"tenantId": ""
}'
components:
schemas:
Measurement:
type: object
description: >
Measurements are used to define the *amount of a unit that is used* for
the price calculation.
*SaaS Product Examples*
* User: the amount of users that are allowed to use the software.
* Member: the amount of members that are allowed to use the software.
* Environment: the amount of environments that are allowed to use the software.
*Hosting Examples*
* CPU: the amount of CPU cores that are used.
* RAM: the amount of RAM that is used.
* Storage: the amount of storage in GB that is used.
* Traffic: the amount of traffic in GB that is used.
* The aggregation type defines *how the amount of units is calculated* during a billing interval.
* The unit defines *what is measured*.
The aggregation types are useful to be more flexible in the billing
process.
Imagine you sell a product with user seats, but you want to bill the
customer for the maximum amount of users that were active during the
billing interval.
In this case you would use the aggregation type "max".
If you want to bill the customer for the sum of all users that were
active during the billing interval, you would use the aggregation type
"sum".
If you want to bill the customer for the average amount of users that
were active during the billing interval, you would use the aggregation
type "avg".
The aggregation type also depends how and when you push the measurements
to the API. Feel free to contact us if you need help.
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.
type:
- string
- 'null'
format: uuid
example: https://example.com/
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
metered:
readOnly: true
type: boolean
tenantId:
readOnly: true
type: string
required:
- unit
- code
Measurement-Read:
type: object
description: >
Measurements are used to define the *amount of a unit that is used* for
the price calculation.
*SaaS Product Examples*
* User: the amount of users that are allowed to use the software.
* Member: the amount of members that are allowed to use the software.
* Environment: the amount of environments that are allowed to use the software.
*Hosting Examples*
* CPU: the amount of CPU cores that are used.
* RAM: the amount of RAM that is used.
* Storage: the amount of storage in GB that is used.
* Traffic: the amount of traffic in GB that is used.
* The aggregation type defines *how the amount of units is calculated* during a billing interval.
* The unit defines *what is measured*.
The aggregation types are useful to be more flexible in the billing
process.
Imagine you sell a product with user seats, but you want to bill the
customer for the maximum amount of users that were active during the
billing interval.
In this case you would use the aggregation type "max".
If you want to bill the customer for the sum of all users that were
active during the billing interval, you would use the aggregation type
"sum".
If you want to bill the customer for the average amount of users that
were active during the billing interval, you would use the aggregation
type "avg".
The aggregation type also depends how and when you push the measurements
to the API. Feel free to contact us if you need help.
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-Read'
- 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
Unit-Read:
type: object
description: ''
deprecated: false
properties:
id:
$ref: '#/components/schemas/UnitId-Read'
readOnly: true
name:
example: Stück
type: string
UnitId-Read:
type: object
description: ''
deprecated: false
securitySchemes:
JWT:
type: http
scheme: bearer
````