> ## 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.
# Set invoice customer address
> Set an invoice address based on an existing customer address. *The vat id will be updated accordingly.* This is available for invoices only.
Required permissions: `invoice:write`
## OpenAPI
````yaml post /invoices/{id}/customer-address
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:
/invoices/{id}/customer-address:
parameters: []
post:
tags:
- Invoice
summary: Set invoice customer address
description: >-
Set an invoice address based on an existing customer address. *The vat
id will be updated accordingly.* This is available for invoices only.
Required permissions: `invoice:write`
operationId: setInvoiceCustomerAddress
parameters:
- name: id
in: path
description: Invoice identifier
required: true
deprecated: false
schema:
type: string
style: simple
explode: false
requestBody:
description: The new Invoice resource
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice.ChangeInvoiceCustomerAddress'
text/html:
schema:
$ref: '#/components/schemas/Invoice.ChangeInvoiceCustomerAddress'
required: true
responses:
'201':
description: Invoice resource created
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice-InvoiceRead'
text/html:
schema:
$ref: '#/components/schemas/Invoice-InvoiceRead'
links: {}
'400':
description: Invalid input
'422':
description: Unprocessable entity
deprecated: false
security:
- JWT:
- invoice:write
x-codeSamples:
- lang: bash
label: cURL
source: |-
curl -X POST \
/invoices/{id}/customer-address \
--header "Content-Type: application/json" \
--header "Authorization: Bearer " \
--data '{
"customerAddressId": "c1a2b3c4-d5e6-4f7a-8b9b-0c1d2e3f4a5b"
}'
components:
schemas:
Invoice.ChangeInvoiceCustomerAddress:
type: object
description: ''
deprecated: false
required:
- customerAddressId
properties:
customerAddressId:
description: >-
The customer address id to change the invoice customer address to.
*The vat id will be updated accordingly.*
example: c1a2b3c4-d5e6-4f7a-8b9b-0c1d2e3f4a5b
type: string
Invoice-InvoiceRead:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
description: The unique identifier of the invoice.
example: 00000000-0000-0000-0000-000000000000
type: string
format: uuid
customer:
$ref: '#/components/schemas/Customer-InvoiceRead'
description: The customer of the invoice.
paymentMethod:
description: >-
The payment method which should be used to fullfill the payment of
the invoice.
anyOf:
- $ref: '#/components/schemas/PaymentMethod-InvoiceRead'
- type: 'null'
referencedInvoice:
description: >-
The referenced invoice of the invoice. This could be in case of a
reminder, refund etc.
anyOf:
- $ref: '#/components/schemas/Invoice-InvoiceRead'
- type: 'null'
type:
description: The type of the invoice.
example: TYPE_INVOICE
enum:
- TYPE_INVOICE
- TYPE_CREDIT
- TYPE_REFUND
- TYPE_REMINDER
- TYPE_CANCEL
- TYPE_DUNNING
currencyCode:
description: >-
The currency code of the invoice. If multiple currency codes will be
used in the positions, they will be converted to that base currency.
example: EUR
type: string
number:
readOnly: true
description: >-
The document id of the invoice. This will be generated, when the
invoice will be finalized.
example: RE-0000000001
type: string
status:
readOnly: true
type: string
enum:
- STATUS_DRAFT
- STATUS_PAID
- STATUS_CANCELLED
- STATUS_CLOSED
- STATUS_REFUNDED
- STATUS_REMINDED
- STATUS_UNPAID
- STATUS_NEW
- STATUS_FINALIZING
creationDate:
readOnly: true
type: string
format: date-time
finalizationDate:
readOnly: true
type:
- string
- 'null'
format: date-time
dueDate:
type:
- string
- 'null'
format: date-time
lastReminderDate:
readOnly: true
type:
- string
- 'null'
format: date-time
lastSentAt:
readOnly: true
type:
- string
- 'null'
format: date-time
dunningLevel:
readOnly: true
type: integer
dunningStatus:
readOnly: true
default: none
example: none
type: string
enum:
- reminder
- dunning
- none
payDate:
readOnly: true
type:
- string
- 'null'
format: date-time
invoiceAddress:
readOnly: true
description: The invoice address of the invoice.
nullable: true
internalNote:
description: The notice of the invoice.
deprecated: true
example: This invoice is with a special discount.
type:
- string
- 'null'
title:
readOnly: true
type:
- string
- 'null'
introduction:
readOnly: true
type:
- string
- 'null'
closing:
readOnly: true
type:
- string
- 'null'
netAmount:
$ref: '#/components/schemas/MoneyEmbedded-InvoiceRead'
readOnly: true
description: The net amount of the invoice.
grossAmount:
$ref: '#/components/schemas/MoneyEmbedded-InvoiceRead'
readOnly: true
taxAmount:
$ref: '#/components/schemas/MoneyEmbedded-InvoiceRead'
readOnly: true
discountAmount:
$ref: '#/components/schemas/MoneyEmbeddedDefaultNull-InvoiceRead'
readOnly: true
description: The total net discount amount of the invoice.
file:
readOnly: true
anyOf:
- $ref: '#/components/schemas/Media-InvoiceRead'
- type: 'null'
xmlFile:
readOnly: true
description: >-
The xml representation of the invoice in EN16931 or x-Rechnung
format.
anyOf:
- $ref: '#/components/schemas/Media-InvoiceRead'
- type: 'null'
positions:
readOnly: true
description: The positions of the invoice.
type: array
items:
$ref: '#/components/schemas/InvoicePositionItem-InvoiceRead'
applicatedExchangeRates:
readOnly: true
description: >-
The applicated exchange rates of the invoice, fetched from the
european central bank.
type: array
items:
$ref: '#/components/schemas/ApplicatedExchangeRate-InvoiceRead'
eInvoiceType:
description: The einvoice generated xml file format.
default: zugferd211
example: zugferd211
enum:
- - factorx
- zugferd211
leitwegId:
description: >-
The leitwegid used for einvoice. This is only set, when the
eInvoiceType is not null.
example: '1234567890123'
type:
- string
- '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)
serviceDateFrom:
readOnly: true
description: The earliest service date of all positions.
type:
- string
- 'null'
format: date-time
serviceDateTo:
readOnly: true
description: The latest service date of all positions.
type:
- string
- 'null'
format: date-time
unpaidAmount:
$ref: '#/components/schemas/Money-InvoiceRead'
readOnly: true
usageBreakdownUrl:
readOnly: true
description: Public url to view the detailed usage breakdown of this invoice.
type:
- string
- 'null'
cancellationDocument:
readOnly: true
description: The referenced cancellation document.
type: object
properties:
number:
type: string
example: 2021-0001
id:
type: string
example: 2021-0001
required:
- number
- id
example:
number: R2021-0001
id: 8d6b0f9e-5b9a-4e1a-9f0a-5e8e1a0b1b1e
nullable: true
dunningDisabled:
readOnly: true
description: Dunning is disabled for this invoice.
type: boolean
sourceType:
readOnly: true
description: |-
Where the invoice was created from.
Possible values:
* `cart`: The invoice was created from a cart.
* `subscription`: The invoice was created from a subscription billing run.
* `manual`: The invoice was created by a user.
Customer-InvoiceRead:
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
companyName:
minLength: 2
maxLength: 255
example: Acme Inc.
type:
- string
- 'null'
datevId:
minLength: 2
maxLength: 255
description: The ID of the customer in DATEV
example: '123456789'
type:
- string
- 'null'
status:
default: STATUS_ACTIVE
example: STATUS_ACTIVE
enum:
- STATUS_ACTIVE
- STATUS_ARCHIVED
- STATUS_SUSPENDED
PaymentMethod-InvoiceRead:
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
referenceId:
type:
- string
- 'null'
description: The reference ID of the payment method at the payment gateway
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
source:
default: api
example: api
type: string
enum:
- checkout
- customerfront
- api
- add_link
description: The source where the payment method was created
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)
data:
type: array
items:
type: string
description: Additional data associated with the payment method
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'
sepaMandate:
readOnly: true
description: >-
The sepa mandate of the payment method, if the gatewayName is
"payment_sepa"
anyOf:
- $ref: '#/components/schemas/SepaMandate-InvoiceRead'
- type: 'null'
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
MoneyEmbedded-InvoiceRead:
type: object
description: ''
deprecated: false
MoneyEmbeddedDefaultNull-InvoiceRead:
type: object
description: ''
deprecated: false
Media-InvoiceRead:
type: object
description: ''
deprecated: false
properties:
id:
$ref: '#/components/schemas/MediaId-InvoiceRead'
readOnly: true
example: 01F9Z3ZJXZQZJZJZJZJZJZJZJZ
isPrivate:
description: Whether the media is public accessible or not
example: true
type: boolean
mimeType:
description: The mime type of the media
example: image/jpeg
type:
- string
- 'null'
fileExtension:
description: The file extension of the media
example: jpg
type: string
fileName:
description: The original file name of the media
example: invoice.jpg
type: string
storageFileName:
description: The file name of the media in the storage
example: 01F9Z3ZJXZQZJZJZJZJZJZJZJZ.jpg
type: string
createdAt:
readOnly: true
description: The date and time when the media was created
example: '2021-01-01T00:00:00+00:00'
type: string
format: date-time
InvoicePositionItem-InvoiceRead:
type: object
description: ''
deprecated: false
properties:
id:
$ref: '#/components/schemas/InvoicePositionItemId-InvoiceRead'
position:
readOnly: true
description: >-
The position of the invoice position item in the invoice. If 0, the
item will be added at the end of the invoice.
type:
- integer
- 'null'
quantity:
$ref: '#/components/schemas/Quantity-InvoiceRead'
description: The quantity of the invoice position item.
example: 1
unit:
description: The unit of the invoice position item.
anyOf:
- $ref: '#/components/schemas/Unit-InvoiceRead'
- type: 'null'
unitPrice:
$ref: '#/components/schemas/MoneyEmbedded-InvoiceRead'
description: The unit price of the invoice position item.
netAmount:
$ref: '#/components/schemas/MoneyEmbedded-InvoiceRead'
readOnly: true
description: The net amount of the invoice position item, before discount.
grossAmount:
$ref: '#/components/schemas/MoneyEmbedded-InvoiceRead'
readOnly: true
description: The gross amount of the invoice position item, after discount.
taxAmount:
$ref: '#/components/schemas/MoneyEmbedded-InvoiceRead'
readOnly: true
description: The tax amount of the invoice position item, after discount.
discountAmount:
$ref: '#/components/schemas/MoneyEmbeddedDefaultNull-InvoiceRead'
description: The discount amount of the invoice position item.
discountPercentage:
description: >-
The discount percentage of the invoice position item. You can either
define an amount or a percentage.
example: 10
type:
- string
- 'null'
discountFixed:
$ref: '#/components/schemas/MoneyEmbeddedDefaultNull-InvoiceRead'
writeOnly: true
description: The fixed applied discount amount of the invoice position item.
name:
description: The description of the invoice position item.
example: My subscription product
type: string
description:
description: The description of the invoice position item.
example: '* my subscription product'
type:
- string
- 'null'
taxGroup:
$ref: '#/components/schemas/TaxGroup-InvoiceRead'
description: >-
The tax group of the invoice position item. Based on the customer
and tax group, the correct tax rate will be calculated.
tax:
readOnly: true
description: >-
The tax of the invoice position item, calculated based on the tax
group.
anyOf:
- $ref: '#/components/schemas/Tax-InvoiceRead'
- type: 'null'
type:
description: The type of the invoice position item.
example: product
type:
- string
- 'null'
enum:
- product
- discount
- setup
- dunning_fee
- invoice
- null
parent:
description: >-
The parent invoice position item. Positions can be defined in a
tree, with a maximum depth of two.
anyOf:
- $ref: '#/components/schemas/InvoicePositionItem-InvoiceRead'
- type: 'null'
group:
description: >-
The invoice position item group. Positions can be grouped together
with a headline, which is shown on the invoice.
anyOf:
- $ref: '#/components/schemas/InvoicePositionItemGroup-InvoiceRead'
- type: 'null'
createdAt:
readOnly: true
description: The creation date of the invoice position item.
example: '2020-01-01T00:00:00+00:00'
type: string
format: date-time
product:
anyOf:
- $ref: '#/components/schemas/Product-InvoiceRead'
- type: 'null'
subscriptionItem:
anyOf:
- $ref: '#/components/schemas/SubscriptionItem-InvoiceRead'
- type: 'null'
serviceDateFrom:
readOnly: true
description: The service date from of the invoice position item.
example: '2020-01-01T00:00:00+00:00'
type:
- string
- 'null'
format: date-time
serviceDateTo:
readOnly: true
description: The service date to of the invoice position item.
example: '2020-01-01T00:00:00+00:00'
type:
- string
- 'null'
format: date-time
ApplicatedExchangeRate-InvoiceRead:
type: object
description: ''
deprecated: false
properties:
sourceCurrencyCode:
example: EUR
type: string
destinationCurrencyCode:
example: CHF
type: string
exchangeRate:
example: '1.135'
type: string
exchangeRateDate:
type: string
format: date-time
Money-InvoiceRead:
type: object
description: ''
deprecated: false
SepaMandate-InvoiceRead:
type: object
description: ''
deprecated: false
MediaId-InvoiceRead:
type: object
description: ''
deprecated: false
InvoicePositionItemId-InvoiceRead:
type: object
description: ''
deprecated: false
Quantity-InvoiceRead:
type:
- number
- 'null'
description: A numeric quantity value.
example: 1
Unit-InvoiceRead:
type: object
description: ''
deprecated: false
properties:
id:
$ref: '#/components/schemas/UnitId-InvoiceRead'
readOnly: true
name:
example: Stück
type: string
TaxGroup-InvoiceRead:
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
Tax-InvoiceRead:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
example: 00000000-0000-0000-0000-000000000000
type: string
description:
maxLength: 255
description: Some internal description
example: 19%
nullable: true
code:
description: Some internal code
example: '19'
type: string
rate:
minimum: 0
maximum: 100
description: Tax rate in percent
example: 19
type: integer
required:
- code
- rate
InvoicePositionItemGroup-InvoiceRead:
type: object
description: ''
deprecated: false
properties:
id:
example: ad8a3b9e-5b0a-4e1a-9c1a-0b9b2b8b0b0b
type: string
ranking:
example: 1
type: integer
name:
example: 'Subscription #12345'
type: string
Product-InvoiceRead:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
description: The unique identifier of the product.
example: ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b
type: string
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'
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
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
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:
- type
SubscriptionItem-InvoiceRead:
type: object
description: ''
deprecated: false
properties:
id:
readOnly: true
example: 01F9ZQZJZJQZJZJZJZJZJZJZJZ
type: string
name:
readOnly: true
description: >-
The name of the item which will be used in the invoice. The name is
translated based on the customer's locale.
example: Fitness M
type: string
description:
readOnly: true
description: >-
The description of the item which will be used in the invoice. The
description is translated based on the customer's locale.
example: Everything included
type:
- string
- 'null'
furtherInformation:
readOnly: true
description: >-
Further information defines additional information for the item
which will be displayed in the invoice.
example: 'Additional agreements: The contract includes a free drink flatrate.'
type:
- string
- 'null'
status:
readOnly: true
description: |-
The status of the item.
Possible values:
* `active`: The item is active and will be billed.
* `canceled`: The item is canceled and will be billed until the end of the contract.
* `pending`: The item is pending and will be billed after the contract start.
* `terminated`: The item is terminated and will not be billed.
example: active
enum:
- active
- canceled
- pending
- terminated
subscriptionId:
readOnly: true
type: string
UnitId-InvoiceRead:
type: object
description: ''
deprecated: false
securitySchemes:
JWT:
type: http
scheme: bearer
````