> ## 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 customer
> Create customer
Required permissions: `customer:write`
## OpenAPI
````yaml post /customers
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:
/customers:
parameters: []
post:
tags:
- Customer
summary: Create customer
description: |-
Create customer
Required permissions: `customer:write`
operationId: createCustomer
parameters: []
requestBody:
description: The new Customer resource
content:
application/json:
schema:
$ref: '#/components/schemas/Customer.CustomerInput-CustomerWrite'
text/html:
schema:
$ref: '#/components/schemas/Customer.CustomerInput-CustomerWrite'
required: true
responses:
'201':
description: Customer resource created
content:
application/json:
schema:
$ref: '#/components/schemas/Customer-CustomerRead'
text/html:
schema:
$ref: '#/components/schemas/Customer-CustomerRead'
links: {}
'400':
description: Invalid input
'422':
description: Unprocessable entity
deprecated: false
security:
- JWT:
- customer:write
x-codeSamples:
- lang: bash
label: cURL
source: |-
curl -X POST \
/customers \
--header "Content-Type: application/json" \
--header "Authorization: Bearer " \
--data '{
"currencyCode": "EUR",
"timeZone": "Europe\/Berlin",
"invoiceEmail": "john.doe@example.com",
"datevId": "123456789",
"vatId": "DE123456789",
"companyName": "Acme Inc.",
"commercialRegisterName": "Amtsgericht Berlin (Charlottenburg)",
"commercialRegisterNumber": "HRB 123456",
"phone": "+49 123 456789",
"street": "Musterstra\u00dfe 1",
"houseNumber": "1a",
"zip": "12345",
"city": "Berlin",
"addition": "c\/o John Doe",
"customFields": {
"field1": "value1",
"field2": "value2"
}
}'
components:
schemas:
Customer.CustomerInput-CustomerWrite:
type: object
description: ''
deprecated: false
properties:
currencyCode:
description: >-
Can be empty. In this case the default currency of the tenant is
used.
externalDocs:
url: https://schema.org/priceCurrency
example: EUR
type:
- string
- 'null'
customerGroup:
description: The customer group of the customer.
example: ad8b3b1b-3b3b-4b3b-8b3b-3b3b3b3b3b3b
nullable: true
contactPerson:
description: The contact person of the customer.
example: ad8b3b1b-3b3b-4b3b-8b3b-3b3b3b3b3b3b
nullable: true
countryCode:
default: DE
example: DE
nullable: true
email:
format: email
minLength: 2
maxLength: 255
description: >-
The email address used for e-mail communication. This is also the
username for the customer login. This needs to be unique.
externalDocs:
url: https://schema.org/email
example: john.doe@example.com
nullable: false
timeZone:
description: >-
The timezone of the customer. This is used for the communication
with the customer or on generating documents like invoices,
reminders, etc.
default: Europe/Berlin
example: Europe/Berlin
type:
- string
- 'null'
firstName:
minLength: 2
maxLength: 255
description: Can be empty if the customer is a company.
example: John
nullable: true
lastName:
minLength: 2
maxLength: 255
description: Can be empty if the customer is a company.
example: Doe
nullable: true
language:
enum:
- de
- en
description: >-
The language of the customer. This is used for the communication
with the customer or on generating documents like invoices,
reminders, etc.
default: de
example: de
invoiceEmail:
format: email
minLength: 2
maxLength: 255
description: >-
This email will be used for sending invoices to the customer. If not
provided, we use the default e-mail address.
externalDocs:
url: https://schema.org/email
example: john.doe@example.com
type:
- string
- 'null'
datevId:
minLength: 2
maxLength: 255
description: >-
The ID of the customer in DATEV. If not provided, we will generate a
datev id, when the "accounting.useDebitorAccounts" setting is set to
true.
example: '123456789'
type:
- string
- 'null'
gender:
description: >-
This field is needed, to fullfill a collection process on a personal
customer.
example: male
enum:
- male
- female
- diverse
vatId:
minLength: 2
maxLength: 255
example: DE123456789
type:
- string
- 'null'
companyName:
minLength: 2
maxLength: 255
example: Acme Inc.
type:
- string
- 'null'
commercialRegisterName:
description: >-
The name of the commercial register. This is needed tofullfill the
collection processes on companies.
example: Amtsgericht Berlin (Charlottenburg)
type:
- string
- 'null'
commercialRegisterNumber:
description: >-
The ID of the customer in the commercial register, e.g. HRB 123456.
This is needed tofullfill the collection processes on companies.
example: HRB 123456
type:
- string
- 'null'
phone:
minLength: 2
maxLength: 255
example: +49 123 456789
type:
- string
- 'null'
customerNumber:
minLength: 2
maxLength: 255
description: >-
Can be empty. In this case the customer number is generated
automatically.
example: CUSTOMER-000
nullable: true
street:
minLength: 2
maxLength: 255
description: >-
The street of the customer. If not provided, we will use empty
string.
example: Musterstraße 1
type:
- string
- 'null'
houseNumber:
minLength: 0
maxLength: 255
description: >-
The house number of the customer. If not provided, we will use empty
string.
example: 1a
type:
- string
- 'null'
zip:
minLength: 2
maxLength: 255
description: >-
The zip code of the customer. If not provided, we will use empty
string.
example: '12345'
type:
- string
- 'null'
city:
minLength: 2
maxLength: 255
description: The city of the customer. If not provided, we will use empty string.
example: Berlin
type:
- string
- 'null'
addition:
minLength: 2
maxLength: 255
description: >-
Additional address line of the customer. If not provided, we will
use empty string.
example: c/o John Doe
type:
- string
- 'null'
invoiceAddress:
description: >-
An invoice address for the customer. If not provided, we will use
the default address.
nullable: true
taxExempt:
description: |-
The tax exemption status of the customer.
Possible values:
* `exempt`: The customer will never be charged with taxes.
* `auto`: The customer will be charged with taxes based on their country and vat id status. If the customer is eligble for reverse-charge the customer will not be charged with taxes.
default: auto
example: auto
enum:
- auto
- exempt
parentCustomerId:
description: >-
Optional parent customer ID to place this customer into an
organization hierarchy. The parent must exist, be active, and belong
to the same tenant. The hierarchy supports a maximum depth of 3
levels. Requires the `customer.hierarchy` feature to be enabled —
ignored otherwise.
example: null
type:
- string
- 'null'
format: uuid
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)
salesChannel:
description: >-
Der Vertriebskanal, dem der Kunde zugeordnet wird, als UUID oder
technischer Name (z. B. "default"). Muss existieren und zur
aktuellen Organisation gehören. Bleibt das Feld bei der Anlage leer,
wird der aktive bzw. Standard-Vertriebskanal zugewiesen.
example: default
type:
- string
- 'null'
required:
- countryCode
- email
Customer-CustomerRead:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
example: 00000000-0000-0000-0000-000000000000
type: string
customerNumber:
minLength: 2
maxLength: 255
example: CUSTOMER-000
nullable: false
timeZone:
readOnly: true
default: Europe/Berlin
example: Europe/Berlin
type: string
firstName:
minLength: 2
maxLength: 255
description: Can be empty if the customer is a company.
example: John
nullable: true
lastName:
minLength: 2
maxLength: 255
description: Can be empty if the customer is a company.
example: Doe
nullable: true
currencyCode:
description: >-
Can be empty. In this case the default currency of the tenant is
used.
externalDocs:
url: https://schema.org/priceCurrency
example: EUR
type: string
countryCode:
example: DE
type: string
companyName:
minLength: 2
maxLength: 255
example: Acme Inc.
type:
- string
- 'null'
vatId:
minLength: 2
maxLength: 255
example: DE123456789
type:
- string
- 'null'
isVatIdValid:
readOnly: true
description: >-
Indicates if the VAT ID is valid. This is only available for EU VAT
IDs. We validate the VAT IDs each night and directly after change.
example: true
type: boolean
taxExempt:
type: string
enum:
- auto
- exempt
datevId:
minLength: 2
maxLength: 255
description: The ID of the customer in DATEV
example: '123456789'
type:
- string
- 'null'
commercialRegisterName:
description: >-
The name of the commercial register. This is needed tofullfill the
collection processes on companies.
example: Amtsgericht Berlin (Charlottenburg)
type:
- string
- 'null'
commercialRegisterNumber:
description: >-
The ID of the customer in the commercial register, e.g. HRB 123456.
This is needed tofullfill the collection processes on companies.
example: HRB 123456
type:
- string
- 'null'
status:
default: STATUS_ACTIVE
example: STATUS_ACTIVE
enum:
- STATUS_ACTIVE
- STATUS_ARCHIVED
- STATUS_SUSPENDED
gender:
description: >-
This field is needed, to fullfill a collection process on a personal
customer.
example: male
enum:
- male
- female
- diverse
phone:
minLength: 2
maxLength: 255
example: +49 123 456789
type:
- string
- 'null'
language:
enum:
- de
- en
description: >-
The language of the customer. This is used for the communication
with the customer or on generating documents like invoices,
reminders, etc.
default: de
example: de
totalTurnOverRank:
readOnly: true
description: >-
The current customer rank, based on their revenue. Lower is better.
This will calculate each night.
example: 10
type:
- integer
- 'null'
createdAt:
readOnly: true
example: '2020-01-01T00:00:00+00:00'
type: string
format: date-time
emailAddresses:
type: array
items:
$ref: '#/components/schemas/CustomerEmail-CustomerRead'
addresses:
type: array
items:
$ref: '#/components/schemas/CustomerAddress-CustomerRead'
customerGroup:
readOnly: true
description: The customer group of the customer.
anyOf:
- $ref: '#/components/schemas/CustomerGroup-CustomerRead'
- type: 'null'
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)
businessCustomer:
readOnly: true
type: boolean
defaultAddress:
readOnly: true
description: >-
The default address of the customer. This is the address that is
used for billing if no other address is specified.
anyOf:
- $ref: '#/components/schemas/CustomerAddress-CustomerRead'
- type: 'null'
defaultInvoiceAddress:
readOnly: true
description: >-
The invoice address of the customer. This is the address that is
used for billing if defined. If not defined, the default address is
used.
anyOf:
- $ref: '#/components/schemas/CustomerAddress-CustomerRead'
- type: 'null'
defaultEmailAddress:
readOnly: true
description: >-
The default email address of the customer. This is the email address
that is used for billing if no other email address is specified.
anyOf:
- $ref: '#/components/schemas/CustomerEmail-CustomerRead'
- type: 'null'
defaultInvoiceEmailAddress:
readOnly: true
description: >-
The invoice email address of the customer. This is the email address
that is used for billing if defined. If not defined, the default
email address is used.
anyOf:
- $ref: '#/components/schemas/CustomerEmail-CustomerRead'
- type: 'null'
defaultPaymentMethod:
readOnly: true
description: >-
The default payment method of the customer. This is the payment
method that is used for billing.
anyOf:
- $ref: '#/components/schemas/PaymentMethod-CustomerRead'
- type: 'null'
contactPerson:
readOnly: true
description: The contact person of the customer.
anyOf:
- $ref: '#/components/schemas/ContactPerson-CustomerRead'
- type: 'null'
isPartner:
readOnly: true
description: Indicates if the customer is a partner.
type: boolean
partner:
readOnly: true
description: >-
The partner of the customer. If a partner is assigned, all existing
and future subscriptions of the customer will be billed to the
default payment method and invoice address of the partner.
anyOf:
- $ref: '#/components/schemas/PartnerResource-CustomerRead'
- type: 'null'
parentCustomer:
readOnly: true
description: >-
The parent customer in the organization hierarchy. Contains a
minimal representation with id, name, and customerNumber. Only
present when the customer.hierarchy feature is enabled.
anyOf:
- type: object
properties:
id:
type: string
format: uuid
example: 00000000-0000-0000-0000-000000000000
name:
type: string
example: Klinik Musterstadt
customerNumber:
type: string
example: CUST-100
- type: 'null'
childrenCount:
readOnly: true
description: The number of direct child customers in the organization hierarchy.
type: integer
example: 3
isParent:
readOnly: true
description: >-
Indicates whether this customer has child customers in the
organization hierarchy.
type: boolean
isChild:
readOnly: true
description: >-
Indicates whether this customer has a parent customer in the
organization hierarchy.
type: boolean
salesChannel:
readOnly: true
description: Der Vertriebskanal, dem der Kunde zugeordnet ist.
anyOf:
- $ref: '#/components/schemas/SalesChannel'
- type: 'null'
required:
- countryCode
CustomerEmail-CustomerRead:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
example: 00000000-0000-0000-0000-000000000000
type: string
email:
format: email
maxLength: 255
externalDocs:
url: https://schema.org/email
example: john.doe@example.com
type: string
receiverName:
maxLength: 255
example: John Doe
type: string
type:
example: TYPE_COMPANY
enum:
- TYPE_COMPANY
- TYPE_INVOICE
default:
example: 'true'
type: boolean
required:
- email
- receiverName
- type
CustomerAddress-CustomerRead:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
type: string
vatId:
description: >-
VAT ID, which will be used to bill to. If not provided, we will use
the customer vat id.
example: DE123456789
type:
- string
- 'null'
type:
example: TYPE_DEFAULT
enum:
- TYPE_DEFAULT
- TYPE_INVOICE
default:
example: 'true'
type: boolean
status:
readOnly: true
example: active
enum:
- active
- archived
city:
example: Berlin
type: string
zip:
example: '12345'
type: string
street:
example: Musterstraße
type: string
houseNumber:
example: 1a
type: string
countryCode:
example: DE
type: string
companyName:
description: Company name, which will be used to bill to.
example: ACME Inc.
type:
- string
- 'null'
salutation:
example: Herr
enum:
- Firma
- Herr
- Frau
addition:
description: >-
Additional address information, which will be shown on generated
documents like invoices, reminders, etc.
example: c/o John Doe
type:
- string
- 'null'
costCentre:
description: >-
Cost centre, which will be shown on generated documents like
invoices, reminders, etc.
example: '123456789'
type:
- string
- 'null'
firstName:
description: >-
First name, which will be shown on generated documents like
invoices, reminders, etc.
example: John
type:
- string
- 'null'
lastName:
description: >-
Last name, which will be shown on generated documents like invoices,
reminders, etc.
example: Doe
type:
- string
- 'null'
CustomerGroup-CustomerRead:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
type: string
name:
maxLength: 255
type: string
description:
maxLength: 255
type:
- string
- 'null'
required:
- name
PaymentMethod-CustomerRead:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
type: string
description: Unique identifier of the payment method
example: c1a2b3c4-d5e6-4f7a-8b9b-0c1d2e3f4a5b
gatewayName:
type: string
enum:
- wallet
- sepa_debit
- stripe
- fake_provider
- paypal
- bank_transfer
- go_cardless
- testing
description: The payment gateway used to process the payment method
type:
type:
- string
- 'null'
enum:
- sepa_debit
- card
- paypal
- bank_transfer
- wallet
- fake_provider
- null
description: The type of the payment method
default:
type: boolean
description: Whether this is the default payment method for the customer
example: true
status:
default: active
example: active
type: string
enum:
- active
- action_required
- expired
- revoked
- gateway_unconfigured
description: The current status of the payment method
enabled:
type: boolean
description: Whether the payment method is enabled for use
example: true
name:
type:
- string
- 'null'
description: Display name of the payment method
example: Visa (4242)
creationDate:
readOnly: true
type: string
format: date-time
description: The date when the payment method was created
example: '2024-01-15T10:30:00+00:00'
expirationDate:
type:
- string
- 'null'
format: date-time
description: The expiration date of the payment method, if applicable
example: '2026-12-31T23:59:59+00:00'
card:
readOnly: true
description: The card data of the payment method, if the type is "card"
type: object
properties:
brand:
type: string
example: Visa
description: The brand of the card
last4:
type: string
example: '4242'
description: The last 4 digits of the card
expMonth:
type: integer
example: 12
description: The expiration month of the card
expYear:
type: integer
example: 2022
description: The expiration year of the card
cardHolder:
type: string
example: Max Mustermann
description: The card holder name
sepaDebit:
readOnly: true
description: >-
The sepa mandate data of the payment method, if the type is
"sepa_debit"
type: object
properties:
iban:
type: string
example: DE8937*********3232
description: The iban of the sepa mandate
bic:
type: string
example: COBADEFFXXX
description: The bic of the sepa mandate
mandateReference:
type: string
example: MNDT-2021-123456
description: The mandate reference of the sepa mandate
signingDate:
type: string
example: '2021-01-01T00:00:00+00:00'
description: The signing date of the sepa mandate
paypal:
readOnly: true
description: The paypal data of the payment method, if the type is "paypal"
type: object
properties:
email:
type: string
example: max@mustermann.de
description: The email of the paypal account
billingAgreementId:
type: string
example: I-1J5gqz2eZvKYlo2C2X2X2X2X
description: The billing agreement id of the paypal account
ContactPerson-CustomerRead:
type: object
description: ''
deprecated: false
properties:
id:
type: string
firstName:
type: string
lastName:
type: string
email:
type: string
avatar:
type:
- string
- 'null'
PartnerResource-CustomerRead:
type: object
description: ''
deprecated: false
properties:
id:
description: The ID of the partner
example: ad8f7e7d-3b3b-4b3b-8b3b-3b3b3b3b3b3b
type: string
name:
description: The name of the partner
example: John Doe
type: string
number:
description: The customer number of the partner
example: '123456'
type: string
email:
description: The email address of the partner
example: partner@example.com
type:
- string
- 'null'
SalesChannel:
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.
securitySchemes:
JWT:
type: http
scheme: bearer
````