> ## 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.
# Credit invoice
> Credit an invoice. This will credit the given positions and send an email to the customer. This is only possible if the invoice is already finalized and paid or partial paid. This is available for invoices only.
Required permissions: `invoice:credit`
## OpenAPI
````yaml post /invoices/{id}/credit
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}/credit:
parameters: []
post:
tags:
- Invoice
summary: Credit invoice
description: >-
Credit an invoice. This will credit the given positions and send an
email to the customer. This is only possible if the invoice is already
finalized and paid or partial paid. This is available for invoices only.
Required permissions: `invoice:credit`
operationId: creditInvoice
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.CreditInvoiceRequest'
text/html:
schema:
$ref: '#/components/schemas/Invoice.CreditInvoiceRequest'
required: true
responses:
'201':
description: Invoice resource created
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice-InvoiceDetail'
text/html:
schema:
$ref: '#/components/schemas/Invoice-InvoiceDetail'
links: {}
'400':
description: Invalid input
'422':
description: Unprocessable entity
deprecated: false
security:
- JWT:
- invoice:credit
x-codeSamples:
- lang: bash
label: cURL
source: |-
curl -X POST \
/invoices/{id}/credit \
--header "Content-Type: application/json" \
--header "Authorization: Bearer " \
--data '{
"positions": [
[]
],
"comment": "",
"paymentMethod": "https:\/\/example.com\/",
"customIntroduction": "",
"customClosing": ""
}'
components:
schemas:
Invoice.CreditInvoiceRequest:
type: object
description: ''
deprecated: false
properties:
positions:
minItems: 1
description: The positions to cancel.
type: array
items:
$ref: '#/components/schemas/CreditInvoicePositionRequest'
comment:
description: Comment for the activity of crediting the invoice.
type:
- string
- 'null'
reason:
description: The reason for crediting the invoice.
default: other
example: other
enum:
- duplicate
- incorrect
- product_unsatisfactory
- order_change
- other
paymentMethod:
description: >-
The payment method for the credit note. The payment method must be
valid and usable.
type: string
format: uuid
example: https://example.com/
customIntroduction:
description: >-
The custom introduction for the credit note. It will be placed over
the generic template.
type:
- string
- 'null'
customClosing:
description: >-
The custom closing for the credit note. It will be placed over the
generic template.
type:
- string
- 'null'
Invoice-InvoiceDetail:
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-InvoiceDetail'
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-InvoiceDetail'
- 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-InvoiceDetail'
- 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-InvoiceDetail'
readOnly: true
description: The net amount of the invoice.
grossAmount:
$ref: '#/components/schemas/MoneyEmbedded-InvoiceDetail'
readOnly: true
taxAmount:
$ref: '#/components/schemas/MoneyEmbedded-InvoiceDetail'
readOnly: true
discountAmount:
$ref: '#/components/schemas/MoneyEmbeddedDefaultNull-InvoiceDetail'
readOnly: true
description: The total net discount amount of the invoice.
file:
readOnly: true
anyOf:
- $ref: '#/components/schemas/Media-InvoiceDetail'
- type: 'null'
xmlFile:
readOnly: true
description: >-
The xml representation of the invoice in EN16931 or x-Rechnung
format.
anyOf:
- $ref: '#/components/schemas/Media-InvoiceDetail'
- type: 'null'
positions:
readOnly: true
description: The positions of the invoice.
type: array
items:
$ref: '#/components/schemas/InvoicePositionItem-InvoiceDetail'
applicatedExchangeRates:
readOnly: true
description: >-
The applicated exchange rates of the invoice, fetched from the
european central bank.
type: array
items:
$ref: '#/components/schemas/ApplicatedExchangeRate-InvoiceDetail'
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-InvoiceDetail'
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
paymentProviderFeeCents:
readOnly: true
description: >-
The total amount of fees for each payment provider, which charges
fees.
type: object
additionalProperties:
type: integer
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.
creditNotes:
readOnly: true
description: The referenced credit notes.
type: array
items:
$ref: '#/components/schemas/Invoice-InvoiceDetail'
CreditInvoicePositionRequest:
type: object
description: ''
deprecated: false
required:
- id
properties:
id:
description: The id of the position to cancel.
type: string
quantity:
description: >-
The quantity to cancel. This cannot be greater than the quantity of
the position. If not set, the whole position will be canceled.
anyOf:
- $ref: '#/components/schemas/Quantity'
- type: 'null'
unitPrice:
description: The unit price of the position to credit amount.
anyOf:
- $ref: '#/components/schemas/Money'
- type: 'null'
Customer-InvoiceDetail:
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-InvoiceDetail:
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-InvoiceDetail'
- 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-InvoiceDetail:
type: object
description: ''
deprecated: false
MoneyEmbeddedDefaultNull-InvoiceDetail:
type: object
description: ''
deprecated: false
Media-InvoiceDetail:
type: object
description: ''
deprecated: false
properties:
id:
$ref: '#/components/schemas/MediaId-InvoiceDetail'
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-InvoiceDetail:
type: object
description: ''
deprecated: false
properties:
id:
$ref: '#/components/schemas/InvoicePositionItemId-InvoiceDetail'
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-InvoiceDetail'
description: The quantity of the invoice position item.
example: 1
unit:
description: The unit of the invoice position item.
anyOf:
- $ref: '#/components/schemas/Unit-InvoiceDetail'
- type: 'null'
unitPrice:
$ref: '#/components/schemas/MoneyEmbedded-InvoiceDetail'
description: The unit price of the invoice position item.
netAmount:
$ref: '#/components/schemas/MoneyEmbedded-InvoiceDetail'
readOnly: true
description: The net amount of the invoice position item, before discount.
grossAmount:
$ref: '#/components/schemas/MoneyEmbedded-InvoiceDetail'
readOnly: true
description: The gross amount of the invoice position item, after discount.
taxAmount:
$ref: '#/components/schemas/MoneyEmbedded-InvoiceDetail'
readOnly: true
description: The tax amount of the invoice position item, after discount.
discountAmount:
$ref: '#/components/schemas/MoneyEmbeddedDefaultNull-InvoiceDetail'
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-InvoiceDetail'
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-InvoiceDetail'
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-InvoiceDetail'
- 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-InvoiceDetail'
- 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-InvoiceDetail'
- 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-InvoiceDetail'
- type: 'null'
subscriptionItem:
anyOf:
- $ref: '#/components/schemas/SubscriptionItem-InvoiceDetail'
- 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-InvoiceDetail:
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-InvoiceDetail:
type: object
description: ''
deprecated: false
Quantity:
type:
- number
- 'null'
description: A numeric quantity value.
example: 1
Money:
type: object
description: ''
deprecated: false
properties:
positiveOrZero:
readOnly: true
type: boolean
negativeOrZero:
readOnly: true
type: boolean
zero:
readOnly: true
type: boolean
notZero:
readOnly: true
type: boolean
positive:
readOnly: true
type: boolean
negative:
readOnly: true
type: boolean
sign:
readOnly: true
description: Returns the sign of this money.
type: integer
precision:
readOnly: true
type: integer
currency:
$ref: '#/components/schemas/CurrencyCode'
readOnly: true
amount:
readOnly: true
type: integer
amountFloat:
readOnly: true
type: number
SepaMandate-InvoiceDetail:
type: object
description: ''
deprecated: false
MediaId-InvoiceDetail:
type: object
description: ''
deprecated: false
InvoicePositionItemId-InvoiceDetail:
type: object
description: ''
deprecated: false
Quantity-InvoiceDetail:
type:
- number
- 'null'
description: A numeric quantity value.
example: 1
Unit-InvoiceDetail:
type: object
description: ''
deprecated: false
properties:
id:
$ref: '#/components/schemas/UnitId-InvoiceDetail'
readOnly: true
name:
example: Stück
type: string
TaxGroup-InvoiceDetail:
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-InvoiceDetail:
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-InvoiceDetail:
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-InvoiceDetail:
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-InvoiceDetail:
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
CurrencyCode:
type: string
description: ISO 4217 currency code.
example: EUR
UnitId-InvoiceDetail:
type: object
description: ''
deprecated: false
securitySchemes:
JWT:
type: http
scheme: bearer
````