Invoices – API reference

Invoice and quote settings

GET/api/v1/invoice-settings

Default texts, GiroCode, validity of quotes, email templates, custom tax notes and automatic handover to dunning.

Response 200 · InvoiceSettings

collectionobjectrequired
- enabledbooleanrequired
  Automatically hand over overdue invoices to dunning as debts
- daysAfterDueintegerrequired
  Days after due date until handover
  0–365
invoiceobjectrequired
- introTextstringrequired
  max. 5000 characters
- closingTextstringrequired
  max. 5000 characters
- showGiroCodebooleanrequired
- paymentTermsDaysinteger | nullrequired
  empty = from company & invoice
  0–365
offerobjectrequired
- introTextstringrequired
  max. 5000 characters
- closingTextstringrequired
  max. 5000 characters
- validityDaysintegerrequired
  1–365
emailobjectrequired
- invoiceSubjectstringrequired
  max. 200 characters
- invoiceMessagestringrequired
  max. 5000 characters
- offerSubjectstringrequired
  max. 200 characters
- offerMessagestringrequired
  max. 5000 characters
- copyToSelfbooleanrequired
taxNoticesobjectrequired
custom mandatory notices per case (empty = default text with legal basis); checked for the mandatory details
- small_businessstring
  max. 500 characters
- reverse_chargestring
  Domestic reverse charge (§ 13b UStG)
  max. 500 characters
- reverse_charge_eustring
  Reverse charge for services to EU businesses
  max. 500 characters
- intra_eu_supplystring
  max. 500 characters
- exportstring
  max. 500 characters
- non_taxablestring
  max. 500 characters
- tax_exemptstring
  VAT exemption under § 4 UStG
  max. 500 characters
numberingobjectrequired
ST-11: a separate range for corrections is recommended but not required by law
- corrections"separate" | "invoice"required
  Number range for invoice corrections and cancellations: separate = own range (default), invoice = invoice range

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/invoice-settings' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "collection": {
    "enabled": false,
    "daysAfterDue": 0
  },
  "invoice": {
    "introText": "string",
    "closingText": "string",
    "showGiroCode": false,
    "paymentTermsDays": 0
  },
  "offer": {
    "introText": "string",
    "closingText": "string",
    "validityDays": 1
  },
  "email": {
    "invoiceSubject": "string",
    "invoiceMessage": "string",
    "offerSubject": "string",
    "offerMessage": "string",
    "copyToSelf": false
  },
  "taxNotices": {
    "small_business": "string",
    "reverse_charge": "string",
    "reverse_charge_eu": "string",
    "intra_eu_supply": "string",
    "export": "string",
    "non_taxable": "string",
    "tax_exempt": "string"
  },
  "numbering": {
    "corrections": "separate"
  }
}

Update invoice and quote settings

PATCH/api/v1/invoice-settings

Permission: invoices:write

Body (JSON) · InvoiceSettingsUpdate

collectionobject
- enabledboolean
  Automatically hand over overdue invoices to dunning as debts
- daysAfterDueinteger
  Days after due date until handover
  0–365
invoiceobject
- introTextstring
  max. 5000 characters
- closingTextstring
  max. 5000 characters
- showGiroCodeboolean
- paymentTermsDaysinteger | null
  empty = from company & invoice
  0–365
offerobject
- introTextstring
  max. 5000 characters
- closingTextstring
  max. 5000 characters
- validityDaysinteger
  1–365
emailobject
- invoiceSubjectstring
  max. 200 characters
- invoiceMessagestring
  max. 5000 characters
- offerSubjectstring
  max. 200 characters
- offerMessagestring
  max. 5000 characters
- copyToSelfboolean
taxNoticesobject
custom mandatory notices per case (empty = default text with legal basis); checked for the mandatory details
- small_businessstring
  max. 500 characters
- reverse_chargestring
  Domestic reverse charge (§ 13b UStG)
  max. 500 characters
- reverse_charge_eustring
  Reverse charge for services to EU businesses
  max. 500 characters
- intra_eu_supplystring
  max. 500 characters
- exportstring
  max. 500 characters
- non_taxablestring
  max. 500 characters
- tax_exemptstring
  VAT exemption under § 4 UStG
  max. 500 characters
numberingobject
- corrections"separate" | "invoice"
  Number range for invoice corrections and cancellations: separate = own range (default), invoice = invoice range

Response 200 · InvoiceSettings

collectionobjectrequired
- enabledbooleanrequired
  Automatically hand over overdue invoices to dunning as debts
- daysAfterDueintegerrequired
  Days after due date until handover
  0–365
invoiceobjectrequired
- introTextstringrequired
  max. 5000 characters
- closingTextstringrequired
  max. 5000 characters
- showGiroCodebooleanrequired
- paymentTermsDaysinteger | nullrequired
  empty = from company & invoice
  0–365
offerobjectrequired
- introTextstringrequired
  max. 5000 characters
- closingTextstringrequired
  max. 5000 characters
- validityDaysintegerrequired
  1–365
emailobjectrequired
- invoiceSubjectstringrequired
  max. 200 characters
- invoiceMessagestringrequired
  max. 5000 characters
- offerSubjectstringrequired
  max. 200 characters
- offerMessagestringrequired
  max. 5000 characters
- copyToSelfbooleanrequired
taxNoticesobjectrequired
custom mandatory notices per case (empty = default text with legal basis); checked for the mandatory details
- small_businessstring
  max. 500 characters
- reverse_chargestring
  Domestic reverse charge (§ 13b UStG)
  max. 500 characters
- reverse_charge_eustring
  Reverse charge for services to EU businesses
  max. 500 characters
- intra_eu_supplystring
  max. 500 characters
- exportstring
  max. 500 characters
- non_taxablestring
  max. 500 characters
- tax_exemptstring
  VAT exemption under § 4 UStG
  max. 500 characters
numberingobjectrequired
ST-11: a separate range for corrections is recommended but not required by law
- corrections"separate" | "invoice"required
  Number range for invoice corrections and cancellations: separate = own range (default), invoice = invoice range

Possible errors: 400, 401, 403, 429, 500

curl -X PATCH 'https://www.debt-flow.io/api/v1/invoice-settings' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "collection": {
    "enabled": false,
    "daysAfterDue": 0
  },
  "invoice": {
    "introText": "string",
    "closingText": "string",
    "showGiroCode": false,
    "paymentTermsDays": 0
  },
  "offer": {
    "introText": "string",
    "closingText": "string",
    "validityDays": 1
  },
  "email": {
    "invoiceSubject": "string",
    "invoiceMessage": "string",
    "offerSubject": "string",
    "offerMessage": "string",
    "copyToSelf": false
  },
  "taxNotices": {
    "small_business": "string",
    "reverse_charge": "string",
    "reverse_charge_eu": "string",
    "intra_eu_supply": "string",
    "export": "string",
    "non_taxable": "string",
    "tax_exempt": "string"
  },
  "numbering": {
    "corrections": "separate"
  }
}'

Response 200

{
  "collection": {
    "enabled": false,
    "daysAfterDue": 0
  },
  "invoice": {
    "introText": "string",
    "closingText": "string",
    "showGiroCode": false,
    "paymentTermsDays": 0
  },
  "offer": {
    "introText": "string",
    "closingText": "string",
    "validityDays": 1
  },
  "email": {
    "invoiceSubject": "string",
    "invoiceMessage": "string",
    "offerSubject": "string",
    "offerMessage": "string",
    "copyToSelf": false
  },
  "taxNotices": {
    "small_business": "string",
    "reverse_charge": "string",
    "reverse_charge_eu": "string",
    "intra_eu_supply": "string",
    "export": "string",
    "non_taxable": "string",
    "tax_exempt": "string"
  },
  "numbering": {
    "corrections": "separate"
  }
}

List invoices

GET/api/v1/invoices

Invoices, credit notes and cancellation invoices, newest first. Filter by status, document type and contact.

Permission: invoices:read

Query parameters

status"draft" | "open" | "partially_paid" | "paid" | "overdue" | "canceled"
type"invoice" | "credit_note" | "cancellation"
contactIdstring
max. 128 characters
limitinteger
Number of entries (1–100)
1–100 · Default: 25
cursorstring
`nextCursor` of the previous page
max. 500 characters

Response 200

object"list"required
dataArray<Invoice>required
- idstringrequired
  max. 128 characters
- object"invoice"required
- type"invoice" | "credit_note" | "cancellation"required
- kind"standard" | "advance" | "final"required
- status"draft" | "open" | "partially_paid" | "paid" | "overdue" | "canceled"required
- numberstring | nullrequired
  Document number; assigned only on finalising
- contactIdstring | nullrequired
  max. 128 characters
- recipientDocumentRecipientrequired
  - namestringrequired
    Company or name
    max. 160 characters
  - additionstring
    Address supplement, e.g. attn. Ms Muster
    max. 160 characters
  - streetstringrequired
    max. 160 characters · Default: ""
  - zipCodestringrequired
    max. 10 characters · Default: ""
  - citystringrequired
    max. 80 characters · Default: ""
  - countrystringrequired
    Country code ISO 3166-1 alpha-2
    max. 2 characters · Default: "DE"
  - emailstring (email)
    Invoice recipient (email)
    max. 254 characters
  - vatIdstring
    Recipient's VAT ID (required for reverse charge/intra-Community supply)
  - leitwegIdstring
    Leitweg-ID (XRechnung to public authorities)
    max. 60 characters
  - einvoiceRecipientType"business" | "public_authority"
    E-invoice recipient profile (from the contact): public_authority requires a Leitweg-ID (ER-08)
  - customerNumberstring
    Customer number (assigned on finalisation)
    max. 40 characters
- senderSenderSnapshot | nullrequired
  Sender snapshot (taken on finalising)
  - companyNamestringrequired
  - ownerNamestring
  - legalFormstring
  - managingDirectorsstring
  - streetstringrequired
  - zipCodestringrequired
  - citystringrequired
  - countryCodestringrequired
  - phonestring
  - emailstring
  - websitestring
  - taxNumberstring
  - vatIdstring
  - smallBusinessbooleanrequired
  - commercialRegisterobject
  - bankobject
  - invoiceFooterstring
- issueDatestring (date) | nullrequired
  Date (YYYY-MM-DD)
- serviceDatestring (date) | nullrequired
  Date (YYYY-MM-DD)
- servicePeriodServicePeriod | nullrequired
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- serviceDateSource"entered" | "period" | "confirmed_issue_date" | "recurring" | "not_applicable" | nullrequired
  Source of the date of supply (ST-13): confirmed_issue_date = confirmed by the user
- issuanceInvoiceIssuance | nullrequired
  Evidence of issue (from finalising, ST-14)
  - finalizedAtstring (date-time)required
    Server time of finalising
  - serverDatestring (date)required
    Calendar day of finalising (Europe/Berlin)
  - issueDatestring (date)required
    Date (YYYY-MM-DD)
  - issueDateSource"finalize_day" | "entered"required
    finalize_day = day of finalising, entered = entered in the draft
  - deviationDaysintegerrequired
    Issue date minus finalising day in days (negative = earlier)
    -9007199254740991–9007199254740991
  - reasonstring | nullrequired
    Reason for a differing issue date
  - numberstring | nullrequired
  - numberRangestringrequired
    Number range
- dueDatestring (date) | nullrequired
  Date (YYYY-MM-DD)
- paymentTermsDaysintegerrequired
  -9007199254740991–9007199254740991
- priceMode"net" | "gross"required
- taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
  Tax treatment of the receipt
- taxNoticestring | nullrequired
  Mandatory notice (§ 19, § 13b, intra-Community supply …)
- taxCaseInvoiceTaxCase | nullrequired
  Tax case (tax assistant); saved at the latest when finalising
  - factsobjectrequired
  - treatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
    Tax treatment of the receipt
  - placeOfSupplystringrequired
    Place of supply (ISO country)
  - legalBasisstringrequired
  - noticeVariantenum | nullrequired
    Case variant of the mandatory notice (ST-03)
    Values: small_business, reverse_charge, reverse_charge_eu, intra_eu_supply, export, non_taxable, tax_exempt
  - ustvaKzstring | nullrequired
    Advance VAT return form field of the tax base (not for standard taxation)
  - reportingArray<"ustva" | "zm" | "none">required
  - confidence"certain" | "likely" | "review"required
  - assumedbooleanrequired
    Facts assumed from the invoice data (not entered)
  - reasonsArray<string>required
  - warningsArray<string>required
- currency"EUR"required
- subjectstringrequired
- introTextstringrequired
- closingTextstringrequired
- referencestringrequired
- linesArray<DocumentLine>required
  - idstring
    stable line item ID (assigned by the server if empty)
    max. 40 characters
  - type"item" | "text" | "subtotal"
    Line item, plain text line or subtotal
    Default: "item"
  - articleIdstring
    Reference to the article master data
    max. 128 characters
  - titlestringrequired
    max. 300 characters
  - descriptionstring
    max. 5000 characters
  - quantitynumber
    -1000000–1000000 · Default: 1
  - unitstring
    Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
    max. 20 characters
  - unitPriceCentsinteger
    Amount in cents
    -100000000000–100000000000 · Default: 0
  - discountPercentnumber
    0–100
  - taxRatenumber
    Tax rate in per cent (19, 7, 0 …)
    0–100 · Default: 19
  - totalCentsinteger
    Amount in cents
    -100000000000–100000000000
  - servicePeriodobject
  - projectIdstring
    max. 128 characters
  - timeEntryIdsArray<string>
    max. 128 characters
- totalsDocumentTotalsrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - groupsArray<object>required
- deductionsArray<InvoiceDeduction>required
  Final invoice: advance payments actually received and deducted (ST-09)
  - invoiceIdstringrequired
    max. 128 characters
  - numberstringrequired
  - issueDatestring (date)required
    Date (YYYY-MM-DD)
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - groupsArray<object>required
  - invoiceGrossCentsinteger
    Invoice amount of the progress invoice (ST-09)
    -100000000000–100000000000
  - unpaidCentsinteger
    Unreceived remainder of the progress invoice – not deducted (ST-09)
    -100000000000–100000000000
- amountDueCentsintegerrequired
  Amount payable (gross less progress invoices)
  -100000000000–100000000000
- paidCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- creditedCentsintegerrequired
  reduced by invoice corrections (progress invoice: incl. the remainder settled with the final invoice)
  -100000000000–100000000000
- deductedCentsinteger | nullrequired
  Progress invoice: amount received and deducted in the final invoice (ST-09)
  -100000000000–100000000000
- supersededCentsinteger | nullrequired
  Progress invoice: unpaid remainder settled with the final invoice (ST-09)
  -100000000000–100000000000
- openCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- relatedInvoiceIdstring | nullrequired
  max. 128 characters
- advanceInvoiceIdsArray<string>required
  max. 128 characters
- offerIdstring | nullrequired
  max. 128 characters
- projectIdstring | nullrequired
  max. 128 characters
- recurringInvoiceIdstring | nullrequired
  max. 128 characters
- canceledByInvoiceIdstring | nullrequired
  Cancellation invoice for this invoice
  max. 128 characters
- debtIdstring | nullrequired
  Debt in dunning (after handover)
  max. 128 characters
- showGiroCodebooleanrequired
- einvoiceFormat"none" | "zugferd" | "xrechnung"required
- language"de" | "en"required
  Document language (fixed on finalisation)
- dispatchobjectrequired
  - countintegerrequired
    -9007199254740991–9007199254740991
  - lastChannel"email" | "post" | nullrequired
  - lastSentAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
- pdfobject | nullrequired
  archived PDF (after finalisation)
  - sha256stringrequired
  - createdAtstring (date-time)required
    Timestamp (ISO 8601)
- lockedbooleanrequired
- lockedAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
- paidAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
- handedOverAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
- updatedAtstring (date-time)required
  Timestamp (ISO 8601)
hasMorebooleanrequired
nextCursorstring | nullrequired

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/invoices' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "invoice",
      "type": "invoice",
      "kind": "standard",
      "status": "draft",
      "number": "string",
      "contactId": "string",
      "recipient": {
        "name": "string",
        "addition": "string",
        "street": "",
        "zipCode": "",
        "city": "",
        "country": "DE",
        "email": "[email protected]",
        "vatId": "string",
        "leitwegId": "string",
        "einvoiceRecipientType": "business",
        "customerNumber": "string"
      },
      "sender": {
        "companyName": null,
        "ownerName": null,
        "legalForm": null,
        "managingDirectors": null,
        "street": null,
        "zipCode": null,
        "city": null,
        "countryCode": null,
        "phone": null,
        "email": null,
        "website": null,
        "taxNumber": null,
        "vatId": null,
        "smallBusiness": null,
        "commercialRegister": null,
        "bank": null,
        "invoiceFooter": null
      },
      "issueDate": "2026-11-01",
      "serviceDate": "2026-11-01",
      "servicePeriod": {
        "from": null,
        "to": null
      },
      "serviceDateSource": "entered",
      "issuance": {
        "finalizedAt": null,
        "serverDate": null,
        "issueDate": null,
        "issueDateSource": null,
        "deviationDays": null,
        "reason": null,
        "number": null,
        "numberRange": null
      },
      "dueDate": "2026-11-01",
      "paymentTermsDays": 0,
      "priceMode": "net",
      "taxTreatment": "regular",
      "taxNotice": "string",
      "taxCase": {
        "facts": null,
        "treatment": null,
        "placeOfSupply": null,
        "legalBasis": null,
        "noticeVariant": null,
        "ustvaKz": null,
        "reporting": null,
        "confidence": null,
        "assumed": null,
        "reasons": null,
        "warnings": null
      },
      "currency": "EUR",
      "subject": "string",
      "introText": "string",
      "closingText": "string",
      "reference": "string",
      "lines": [
        {
          "id": null,
          "type": null,
          "articleId": null,
          "title": null,
          "description": null,
          "quantity": null,
          "unit": null,
          "unitPriceCents": null,
          "discountPercent": null,
          "taxRate": null,
          "totalCents": null,
          "servicePeriod": null,
          "projectId": null,
          "timeEntryIds": null
        }
      ],
      "totals": {
        "netCents": 0,
        "taxCents": 0,
        "grossCents": 0,
        "groups": [
          null
        ]
      },
      "deductions": [
        {
          "invoiceId": null,
          "number": null,
          "issueDate": null,
          "netCents": null,
          "taxCents": null,
          "grossCents": null,
          "groups": null,
          "invoiceGrossCents": null,
          "unpaidCents": null
        }
      ],
      "amountDueCents": 0,
      "paidCents": 0,
      "creditedCents": 0,
      "deductedCents": 0,
      "supersededCents": 0,
      "openCents": 0,
      "relatedInvoiceId": "string",
      "advanceInvoiceIds": [
        "string"
      ],
      "offerId": "string",
      "projectId": "string",
      "recurringInvoiceId": "string",
      "canceledByInvoiceId": "string",
      "debtId": "string",
      "showGiroCode": false,
      "einvoiceFormat": "none",
      "language": "de",
      "dispatch": {
        "count": 0,
        "lastChannel": "email",
        "lastSentAt": "2026-11-01T09:30:00.000Z"
      },
      "pdf": {
        "sha256": "string",
        "createdAt": "2026-11-01T09:30:00.000Z"
      },
      "locked": false,
      "lockedAt": "2026-11-01T09:30:00.000Z",
      "paidAt": "2026-11-01T09:30:00.000Z",
      "handedOverAt": "2026-11-01T09:30:00.000Z",
      "createdAt": "2026-11-01T09:30:00.000Z",
      "updatedAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Creates a draft (without a number). Recipient, payment terms, tax treatment and pricing mode are – if not specified – taken from the contact or from Company & invoicing respectively. The server calculates the totals. type: credit_note with relatedInvoiceId creates a credit note (invoice correction); if no line items are given, those of the invoice are copied.

Permission: invoices:write

Headers

Idempotency-Keystring
Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
max. 255 characters

Body (JSON) · InvoiceCreate

type"invoice" | "credit_note"
Cancellation invoices are created via POST /invoices/{id}/cancel
Default: "invoice"
kind"standard" | "advance" | "final"
standard = invoice, advance = progress invoice, final = final invoice
contactIdstring | null
Contact (customer) from /contacts
max. 128 characters
recipientDocumentRecipient
Recipient; if omitted, taken from the contact
- namestringrequired
  Company or name
  max. 160 characters
- additionstring
  Address supplement, e.g. attn. Ms Muster
  max. 160 characters
- streetstringrequired
  max. 160 characters · Default: ""
- zipCodestringrequired
  max. 10 characters · Default: ""
- citystringrequired
  max. 80 characters · Default: ""
- countrystringrequired
  Country code ISO 3166-1 alpha-2
  max. 2 characters · Default: "DE"
- emailstring (email)
  Invoice recipient (email)
  max. 254 characters
- vatIdstring
  Recipient's VAT ID (required for reverse charge/intra-Community supply)
- leitwegIdstring
  Leitweg-ID (XRechnung to public authorities)
  max. 60 characters
- einvoiceRecipientType"business" | "public_authority"
  E-invoice recipient profile (from the contact): public_authority requires a Leitweg-ID (ER-08)
- customerNumberstring
  Customer number (assigned on finalisation)
  max. 40 characters
issueDatestring (date) | null
Invoice date; empty = day of finalisation
serviceDatestring (date) | null
Delivery/service date
servicePeriodServicePeriod | null
Service period (instead of service date)
- fromstring (date)required
  Date (YYYY-MM-DD)
- tostring (date)required
  Date (YYYY-MM-DD)
dueDatestring (date) | null
Due date; empty = invoice date + payment term
paymentTermsDaysinteger
Payment term in days
0–365
priceMode"net" | "gross"
Unit prices net (B2B) or gross (B2C)
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"
Tax treatment of the receipt
subjectstring
Subject; empty = “Invoice <number>”
max. 200 characters
introTextstring
max. 5000 characters
closingTextstring
max. 5000 characters
referencestring
Customer's order number/reference
max. 100 characters
linesArray<DocumentLine>
- idstring
  stable line item ID (assigned by the server if empty)
  max. 40 characters
- type"item" | "text" | "subtotal"
  Line item, plain text line or subtotal
  Default: "item"
- articleIdstring
  Reference to the article master data
  max. 128 characters
- titlestringrequired
  max. 300 characters
- descriptionstring
  max. 5000 characters
- quantitynumber
  -1000000–1000000 · Default: 1
- unitstring
  Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
  max. 20 characters
- unitPriceCentsinteger
  Amount in cents
  -100000000000–100000000000 · Default: 0
- discountPercentnumber
  0–100
- taxRatenumber
  Tax rate in per cent (19, 7, 0 …)
  0–100 · Default: 19
- totalCentsinteger
  Amount in cents
  -100000000000–100000000000
- servicePeriodobject
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- projectIdstring
  max. 128 characters
- timeEntryIdsArray<string>
  max. 128 characters
relatedInvoiceIdstring | null
Credit note: corrected invoice
max. 128 characters
advanceInvoiceIdsArray<string>
Final invoice: progress invoices to deduct
max. 128 characters
offerIdstring | null
max. 128 characters
projectIdstring | null
max. 128 characters
showGiroCodeboolean
Print GiroCode (EPC QR) on the PDF
einvoiceFormat"none" | "zugferd" | "xrechnung"
E-invoice format (generation: E-invoice module)
taxFactsSaleTaxFacts | null
Facts for the tax assistant; the server derives the tax case from them (ST-16)
- kind"goods" | "service" | "construction" | "property_service" | "electronic_service"required
  Type of supply
- smallBusinessboolean
  own small-business status; if omitted, taken from Company & invoicing
- customerCountrystringrequired
  Country of residence of the recipient
  max. 2 characters
- customerIsBusinessbooleanrequired
  Recipient is a business and receives the supply for its business
- customerVatIdValidbooleanrequired
  a valid VAT ID of the recipient is available
- destinationCountrystring | null
  Supply of goods: country of destination
  max. 2 characters
- propertyCountrystring | null
  Service related to real estate: location of the property
  max. 2 characters
- exemption"§ 4 Nr. 8 UStG" | "§ 4 Nr. 11 UStG" | "§ 4 Nr. 12 UStG" | "§ 4 Nr. 14 UStG" | "§ 4 Nr. 21 UStG" | "other" | null
  VAT exemption without input VAT deduction
language"de" | "en" | null
Document language (PDF, email, free texts of the e-invoice); empty/null = the contact's language. Fixed on finalisation.

Response 201 · Invoice

idstringrequired
max. 128 characters
object"invoice"required
type"invoice" | "credit_note" | "cancellation"required
kind"standard" | "advance" | "final"required
status"draft" | "open" | "partially_paid" | "paid" | "overdue" | "canceled"required
numberstring | nullrequired
Document number; assigned only on finalising
contactIdstring | nullrequired
max. 128 characters
recipientDocumentRecipientrequired
- namestringrequired
  Company or name
  max. 160 characters
- additionstring
  Address supplement, e.g. attn. Ms Muster
  max. 160 characters
- streetstringrequired
  max. 160 characters · Default: ""
- zipCodestringrequired
  max. 10 characters · Default: ""
- citystringrequired
  max. 80 characters · Default: ""
- countrystringrequired
  Country code ISO 3166-1 alpha-2
  max. 2 characters · Default: "DE"
- emailstring (email)
  Invoice recipient (email)
  max. 254 characters
- vatIdstring
  Recipient's VAT ID (required for reverse charge/intra-Community supply)
- leitwegIdstring
  Leitweg-ID (XRechnung to public authorities)
  max. 60 characters
- einvoiceRecipientType"business" | "public_authority"
  E-invoice recipient profile (from the contact): public_authority requires a Leitweg-ID (ER-08)
- customerNumberstring
  Customer number (assigned on finalisation)
  max. 40 characters
senderSenderSnapshot | nullrequired
Sender snapshot (taken on finalising)
- companyNamestringrequired
- ownerNamestring
- legalFormstring
- managingDirectorsstring
- streetstringrequired
- zipCodestringrequired
- citystringrequired
- countryCodestringrequired
- phonestring
- emailstring
- websitestring
- taxNumberstring
- vatIdstring
- smallBusinessbooleanrequired
- commercialRegisterobject
  - courtstring
  - numberstring
- bankobject
  - accountHolderstring
  - ibanstring
  - bicstring
  - bankNamestring
- invoiceFooterstring
issueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
serviceDatestring (date) | nullrequired
Date (YYYY-MM-DD)
servicePeriodServicePeriod | nullrequired
- fromstring (date)required
  Date (YYYY-MM-DD)
- tostring (date)required
  Date (YYYY-MM-DD)
serviceDateSource"entered" | "period" | "confirmed_issue_date" | "recurring" | "not_applicable" | nullrequired
Source of the date of supply (ST-13): confirmed_issue_date = confirmed by the user
issuanceInvoiceIssuance | nullrequired
Evidence of issue (from finalising, ST-14)
- finalizedAtstring (date-time)required
  Server time of finalising
- serverDatestring (date)required
  Calendar day of finalising (Europe/Berlin)
- issueDatestring (date)required
  Date (YYYY-MM-DD)
- issueDateSource"finalize_day" | "entered"required
  finalize_day = day of finalising, entered = entered in the draft
- deviationDaysintegerrequired
  Issue date minus finalising day in days (negative = earlier)
  -9007199254740991–9007199254740991
- reasonstring | nullrequired
  Reason for a differing issue date
- numberstring | nullrequired
- numberRangestringrequired
  Number range
dueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
paymentTermsDaysintegerrequired
-9007199254740991–9007199254740991
priceMode"net" | "gross"required
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
Tax treatment of the receipt
taxNoticestring | nullrequired
Mandatory notice (§ 19, § 13b, intra-Community supply …)
taxCaseInvoiceTaxCase | nullrequired
Tax case (tax assistant); saved at the latest when finalising
- factsobjectrequired
  - kind"goods" | "service" | "construction" | "property_service" | "electronic_service"required
    Type of supply
  - smallBusinessbooleanrequired
  - customerCountrystringrequired
    Country of residence of the recipient
    max. 2 characters
  - customerIsBusinessbooleanrequired
    Recipient is a business and receives the supply for its business
  - customerVatIdValidbooleanrequired
    a valid VAT ID of the recipient is available
  - destinationCountrystring | null
    Supply of goods: country of destination
    max. 2 characters
  - propertyCountrystring | null
    Service related to real estate: location of the property
    max. 2 characters
  - exemption"§ 4 Nr. 8 UStG" | "§ 4 Nr. 11 UStG" | "§ 4 Nr. 12 UStG" | "§ 4 Nr. 14 UStG" | "§ 4 Nr. 21 UStG" | "other" | null
    VAT exemption without input VAT deduction
- treatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
  Tax treatment of the receipt
- placeOfSupplystringrequired
  Place of supply (ISO country)
- legalBasisstringrequired
- noticeVariantenum | nullrequired
  Case variant of the mandatory notice (ST-03)
  Values: small_business, reverse_charge, reverse_charge_eu, intra_eu_supply, export, non_taxable, tax_exempt
- ustvaKzstring | nullrequired
  Advance VAT return form field of the tax base (not for standard taxation)
- reportingArray<"ustva" | "zm" | "none">required
- confidence"certain" | "likely" | "review"required
- assumedbooleanrequired
  Facts assumed from the invoice data (not entered)
- reasonsArray<string>required
- warningsArray<string>required
currency"EUR"required
subjectstringrequired
introTextstringrequired
closingTextstringrequired
referencestringrequired
linesArray<DocumentLine>required
- idstring
  stable line item ID (assigned by the server if empty)
  max. 40 characters
- type"item" | "text" | "subtotal"
  Line item, plain text line or subtotal
  Default: "item"
- articleIdstring
  Reference to the article master data
  max. 128 characters
- titlestringrequired
  max. 300 characters
- descriptionstring
  max. 5000 characters
- quantitynumber
  -1000000–1000000 · Default: 1
- unitstring
  Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
  max. 20 characters
- unitPriceCentsinteger
  Amount in cents
  -100000000000–100000000000 · Default: 0
- discountPercentnumber
  0–100
- taxRatenumber
  Tax rate in per cent (19, 7, 0 …)
  0–100 · Default: 19
- totalCentsinteger
  Amount in cents
  -100000000000–100000000000
- servicePeriodobject
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- projectIdstring
  max. 128 characters
- timeEntryIdsArray<string>
  max. 128 characters
totalsDocumentTotalsrequired
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - categorystringrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
deductionsArray<InvoiceDeduction>required
Final invoice: advance payments actually received and deducted (ST-09)
- invoiceIdstringrequired
  max. 128 characters
- numberstringrequired
- issueDatestring (date)required
  Date (YYYY-MM-DD)
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
- invoiceGrossCentsinteger
  Invoice amount of the progress invoice (ST-09)
  -100000000000–100000000000
- unpaidCentsinteger
  Unreceived remainder of the progress invoice – not deducted (ST-09)
  -100000000000–100000000000
amountDueCentsintegerrequired
Amount payable (gross less progress invoices)
-100000000000–100000000000
paidCentsintegerrequired
Amount in cents
-100000000000–100000000000
creditedCentsintegerrequired
reduced by invoice corrections (progress invoice: incl. the remainder settled with the final invoice)
-100000000000–100000000000
deductedCentsinteger | nullrequired
Progress invoice: amount received and deducted in the final invoice (ST-09)
-100000000000–100000000000
supersededCentsinteger | nullrequired
Progress invoice: unpaid remainder settled with the final invoice (ST-09)
-100000000000–100000000000
openCentsintegerrequired
Amount in cents
-100000000000–100000000000
relatedInvoiceIdstring | nullrequired
max. 128 characters
advanceInvoiceIdsArray<string>required
max. 128 characters
offerIdstring | nullrequired
max. 128 characters
projectIdstring | nullrequired
max. 128 characters
recurringInvoiceIdstring | nullrequired
max. 128 characters
canceledByInvoiceIdstring | nullrequired
Cancellation invoice for this invoice
max. 128 characters
debtIdstring | nullrequired
Debt in dunning (after handover)
max. 128 characters
showGiroCodebooleanrequired
einvoiceFormat"none" | "zugferd" | "xrechnung"required
language"de" | "en"required
Document language (fixed on finalisation)
dispatchobjectrequired
- countintegerrequired
  -9007199254740991–9007199254740991
- lastChannel"email" | "post" | nullrequired
- lastSentAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
pdfobject | nullrequired
archived PDF (after finalisation)
- sha256stringrequired
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
lockedbooleanrequired
lockedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
paidAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
handedOverAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/invoices' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "invoice",
  "kind": "standard",
  "contactId": "string",
  "recipient": {
    "name": "string",
    "addition": "string",
    "street": "",
    "zipCode": "",
    "city": "",
    "country": "DE",
    "email": "[email protected]",
    "vatId": "string",
    "leitwegId": "string",
    "einvoiceRecipientType": "business",
    "customerNumber": "string"
  },
  "issueDate": "2026-11-01",
  "serviceDate": "2026-11-01",
  "servicePeriod": {
    "from": "2026-11-01",
    "to": "2026-11-01"
  },
  "dueDate": "2026-11-01",
  "paymentTermsDays": 0,
  "priceMode": "net",
  "taxTreatment": "regular",
  "subject": "string",
  "introText": "string",
  "closingText": "string",
  "reference": "string",
  "lines": [],
  "relatedInvoiceId": "string",
  "advanceInvoiceIds": [
    "string"
  ],
  "offerId": "string",
  "projectId": "string",
  "showGiroCode": false,
  "einvoiceFormat": "none",
  "taxFacts": {
    "kind": "goods",
    "smallBusiness": false,
    "customerCountry": "string",
    "customerIsBusiness": false,
    "customerVatIdValid": false,
    "destinationCountry": "string",
    "propertyCountry": "string",
    "exemption": "§ 4 Nr. 8 UStG"
  },
  "language": "de"
}'

Response 201

{
  "id": "string",
  "object": "invoice",
  "type": "invoice",
  "kind": "standard",
  "status": "draft",
  "number": "string",
  "contactId": "string",
  "recipient": {
    "name": "string",
    "addition": "string",
    "street": "",
    "zipCode": "",
    "city": "",
    "country": "DE",
    "email": "[email protected]",
    "vatId": "string",
    "leitwegId": "string",
    "einvoiceRecipientType": "business",
    "customerNumber": "string"
  },
  "sender": {
    "companyName": "string",
    "ownerName": "string",
    "legalForm": "string",
    "managingDirectors": "string",
    "street": "string",
    "zipCode": "string",
    "city": "string",
    "countryCode": "string",
    "phone": "string",
    "email": "string",
    "website": "string",
    "taxNumber": "string",
    "vatId": "string",
    "smallBusiness": false,
    "commercialRegister": {
      "court": "string",
      "number": "string"
    },
    "bank": {
      "accountHolder": "string",
      "iban": "string",
      "bic": "string",
      "bankName": "string"
    },
    "invoiceFooter": "string"
  },
  "issueDate": "2026-11-01",
  "serviceDate": "2026-11-01",
  "servicePeriod": {
    "from": "2026-11-01",
    "to": "2026-11-01"
  },
  "serviceDateSource": "entered",
  "issuance": {
    "finalizedAt": "2026-11-01T09:30:00.000Z",
    "serverDate": "2026-11-01",
    "issueDate": "2026-11-01",
    "issueDateSource": "finalize_day",
    "deviationDays": 0,
    "reason": "string",
    "number": "string",
    "numberRange": "string"
  },
  "dueDate": "2026-11-01",
  "paymentTermsDays": 0,
  "priceMode": "net",
  "taxTreatment": "regular",
  "taxNotice": "string",
  "taxCase": {
    "facts": {
      "kind": "goods",
      "smallBusiness": false,
      "customerCountry": "string",
      "customerIsBusiness": false,
      "customerVatIdValid": false,
      "destinationCountry": null,
      "propertyCountry": null,
      "exemption": null
    },
    "treatment": "regular",
    "placeOfSupply": "string",
    "legalBasis": "string",
    "noticeVariant": "small_business",
    "ustvaKz": "string",
    "reporting": [
      "ustva"
    ],
    "confidence": "certain",
    "assumed": false,
    "reasons": [
      "string"
    ],
    "warnings": [
      "string"
    ]
  },
  "currency": "EUR",
  "subject": "string",
  "introText": "string",
  "closingText": "string",
  "reference": "string",
  "lines": [
    {
      "id": "string",
      "type": "item",
      "articleId": "string",
      "title": "string",
      "description": "string",
      "quantity": 1,
      "unit": "string",
      "unitPriceCents": 0,
      "discountPercent": 0,
      "taxRate": 19,
      "totalCents": 0,
      "servicePeriod": {
        "from": "2026-11-01",
        "to": "2026-11-01"
      },
      "projectId": "string",
      "timeEntryIds": [
        "string"
      ]
    }
  ],
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0,
    "groups": [
      {
        "taxRate": 0,
        "category": "string",
        "netCents": 0,
        "taxCents": 0,
        "grossCents": 0
      }
    ]
  },
  "deductions": [
    {
      "invoiceId": "string",
      "number": "string",
      "issueDate": "2026-11-01",
      "netCents": 0,
      "taxCents": 0,
      "grossCents": 0,
      "groups": [
        {
          "taxRate": null,
          "netCents": null,
          "taxCents": null
        }
      ],
      "invoiceGrossCents": 0,
      "unpaidCents": 0
    }
  ],
  "amountDueCents": 0,
  "paidCents": 0,
  "creditedCents": 0,
  "deductedCents": 0,
  "supersededCents": 0,
  "openCents": 0,
  "relatedInvoiceId": "string",
  "advanceInvoiceIds": [
    "string"
  ],
  "offerId": "string",
  "projectId": "string",
  "recurringInvoiceId": "string",
  "canceledByInvoiceId": "string",
  "debtId": "string",
  "showGiroCode": false,
  "einvoiceFormat": "none",
  "language": "de",
  "dispatch": {
    "count": 0,
    "lastChannel": "email",
    "lastSentAt": "2026-11-01T09:30:00.000Z"
  },
  "pdf": {
    "sha256": "string",
    "createdAt": "2026-11-01T09:30:00.000Z"
  },
  "locked": false,
  "lockedAt": "2026-11-01T09:30:00.000Z",
  "paidAt": "2026-11-01T09:30:00.000Z",
  "handedOverAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Retrieve invoice

GET/api/v1/invoices/{id}

Permission: invoices:read

Path parameters

idstringrequired
Resource ID
max. 128 characters

Response 200 · Invoice

idstringrequired
max. 128 characters
object"invoice"required
type"invoice" | "credit_note" | "cancellation"required
kind"standard" | "advance" | "final"required
status"draft" | "open" | "partially_paid" | "paid" | "overdue" | "canceled"required
numberstring | nullrequired
Document number; assigned only on finalising
contactIdstring | nullrequired
max. 128 characters
recipientDocumentRecipientrequired
- namestringrequired
  Company or name
  max. 160 characters
- additionstring
  Address supplement, e.g. attn. Ms Muster
  max. 160 characters
- streetstringrequired
  max. 160 characters · Default: ""
- zipCodestringrequired
  max. 10 characters · Default: ""
- citystringrequired
  max. 80 characters · Default: ""
- countrystringrequired
  Country code ISO 3166-1 alpha-2
  max. 2 characters · Default: "DE"
- emailstring (email)
  Invoice recipient (email)
  max. 254 characters
- vatIdstring
  Recipient's VAT ID (required for reverse charge/intra-Community supply)
- leitwegIdstring
  Leitweg-ID (XRechnung to public authorities)
  max. 60 characters
- einvoiceRecipientType"business" | "public_authority"
  E-invoice recipient profile (from the contact): public_authority requires a Leitweg-ID (ER-08)
- customerNumberstring
  Customer number (assigned on finalisation)
  max. 40 characters
senderSenderSnapshot | nullrequired
Sender snapshot (taken on finalising)
- companyNamestringrequired
- ownerNamestring
- legalFormstring
- managingDirectorsstring
- streetstringrequired
- zipCodestringrequired
- citystringrequired
- countryCodestringrequired
- phonestring
- emailstring
- websitestring
- taxNumberstring
- vatIdstring
- smallBusinessbooleanrequired
- commercialRegisterobject
  - courtstring
  - numberstring
- bankobject
  - accountHolderstring
  - ibanstring
  - bicstring
  - bankNamestring
- invoiceFooterstring
issueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
serviceDatestring (date) | nullrequired
Date (YYYY-MM-DD)
servicePeriodServicePeriod | nullrequired
- fromstring (date)required
  Date (YYYY-MM-DD)
- tostring (date)required
  Date (YYYY-MM-DD)
serviceDateSource"entered" | "period" | "confirmed_issue_date" | "recurring" | "not_applicable" | nullrequired
Source of the date of supply (ST-13): confirmed_issue_date = confirmed by the user
issuanceInvoiceIssuance | nullrequired
Evidence of issue (from finalising, ST-14)
- finalizedAtstring (date-time)required
  Server time of finalising
- serverDatestring (date)required
  Calendar day of finalising (Europe/Berlin)
- issueDatestring (date)required
  Date (YYYY-MM-DD)
- issueDateSource"finalize_day" | "entered"required
  finalize_day = day of finalising, entered = entered in the draft
- deviationDaysintegerrequired
  Issue date minus finalising day in days (negative = earlier)
  -9007199254740991–9007199254740991
- reasonstring | nullrequired
  Reason for a differing issue date
- numberstring | nullrequired
- numberRangestringrequired
  Number range
dueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
paymentTermsDaysintegerrequired
-9007199254740991–9007199254740991
priceMode"net" | "gross"required
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
Tax treatment of the receipt
taxNoticestring | nullrequired
Mandatory notice (§ 19, § 13b, intra-Community supply …)
taxCaseInvoiceTaxCase | nullrequired
Tax case (tax assistant); saved at the latest when finalising
- factsobjectrequired
  - kind"goods" | "service" | "construction" | "property_service" | "electronic_service"required
    Type of supply
  - smallBusinessbooleanrequired
  - customerCountrystringrequired
    Country of residence of the recipient
    max. 2 characters
  - customerIsBusinessbooleanrequired
    Recipient is a business and receives the supply for its business
  - customerVatIdValidbooleanrequired
    a valid VAT ID of the recipient is available
  - destinationCountrystring | null
    Supply of goods: country of destination
    max. 2 characters
  - propertyCountrystring | null
    Service related to real estate: location of the property
    max. 2 characters
  - exemption"§ 4 Nr. 8 UStG" | "§ 4 Nr. 11 UStG" | "§ 4 Nr. 12 UStG" | "§ 4 Nr. 14 UStG" | "§ 4 Nr. 21 UStG" | "other" | null
    VAT exemption without input VAT deduction
- treatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
  Tax treatment of the receipt
- placeOfSupplystringrequired
  Place of supply (ISO country)
- legalBasisstringrequired
- noticeVariantenum | nullrequired
  Case variant of the mandatory notice (ST-03)
  Values: small_business, reverse_charge, reverse_charge_eu, intra_eu_supply, export, non_taxable, tax_exempt
- ustvaKzstring | nullrequired
  Advance VAT return form field of the tax base (not for standard taxation)
- reportingArray<"ustva" | "zm" | "none">required
- confidence"certain" | "likely" | "review"required
- assumedbooleanrequired
  Facts assumed from the invoice data (not entered)
- reasonsArray<string>required
- warningsArray<string>required
currency"EUR"required
subjectstringrequired
introTextstringrequired
closingTextstringrequired
referencestringrequired
linesArray<DocumentLine>required
- idstring
  stable line item ID (assigned by the server if empty)
  max. 40 characters
- type"item" | "text" | "subtotal"
  Line item, plain text line or subtotal
  Default: "item"
- articleIdstring
  Reference to the article master data
  max. 128 characters
- titlestringrequired
  max. 300 characters
- descriptionstring
  max. 5000 characters
- quantitynumber
  -1000000–1000000 · Default: 1
- unitstring
  Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
  max. 20 characters
- unitPriceCentsinteger
  Amount in cents
  -100000000000–100000000000 · Default: 0
- discountPercentnumber
  0–100
- taxRatenumber
  Tax rate in per cent (19, 7, 0 …)
  0–100 · Default: 19
- totalCentsinteger
  Amount in cents
  -100000000000–100000000000
- servicePeriodobject
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- projectIdstring
  max. 128 characters
- timeEntryIdsArray<string>
  max. 128 characters
totalsDocumentTotalsrequired
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - categorystringrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
deductionsArray<InvoiceDeduction>required
Final invoice: advance payments actually received and deducted (ST-09)
- invoiceIdstringrequired
  max. 128 characters
- numberstringrequired
- issueDatestring (date)required
  Date (YYYY-MM-DD)
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
- invoiceGrossCentsinteger
  Invoice amount of the progress invoice (ST-09)
  -100000000000–100000000000
- unpaidCentsinteger
  Unreceived remainder of the progress invoice – not deducted (ST-09)
  -100000000000–100000000000
amountDueCentsintegerrequired
Amount payable (gross less progress invoices)
-100000000000–100000000000
paidCentsintegerrequired
Amount in cents
-100000000000–100000000000
creditedCentsintegerrequired
reduced by invoice corrections (progress invoice: incl. the remainder settled with the final invoice)
-100000000000–100000000000
deductedCentsinteger | nullrequired
Progress invoice: amount received and deducted in the final invoice (ST-09)
-100000000000–100000000000
supersededCentsinteger | nullrequired
Progress invoice: unpaid remainder settled with the final invoice (ST-09)
-100000000000–100000000000
openCentsintegerrequired
Amount in cents
-100000000000–100000000000
relatedInvoiceIdstring | nullrequired
max. 128 characters
advanceInvoiceIdsArray<string>required
max. 128 characters
offerIdstring | nullrequired
max. 128 characters
projectIdstring | nullrequired
max. 128 characters
recurringInvoiceIdstring | nullrequired
max. 128 characters
canceledByInvoiceIdstring | nullrequired
Cancellation invoice for this invoice
max. 128 characters
debtIdstring | nullrequired
Debt in dunning (after handover)
max. 128 characters
showGiroCodebooleanrequired
einvoiceFormat"none" | "zugferd" | "xrechnung"required
language"de" | "en"required
Document language (fixed on finalisation)
dispatchobjectrequired
- countintegerrequired
  -9007199254740991–9007199254740991
- lastChannel"email" | "post" | nullrequired
- lastSentAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
pdfobject | nullrequired
archived PDF (after finalisation)
- sha256stringrequired
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
lockedbooleanrequired
lockedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
paidAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
handedOverAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/invoices/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "id": "string",
  "object": "invoice",
  "type": "invoice",
  "kind": "standard",
  "status": "draft",
  "number": "string",
  "contactId": "string",
  "recipient": {
    "name": "string",
    "addition": "string",
    "street": "",
    "zipCode": "",
    "city": "",
    "country": "DE",
    "email": "[email protected]",
    "vatId": "string",
    "leitwegId": "string",
    "einvoiceRecipientType": "business",
    "customerNumber": "string"
  },
  "sender": {
    "companyName": "string",
    "ownerName": "string",
    "legalForm": "string",
    "managingDirectors": "string",
    "street": "string",
    "zipCode": "string",
    "city": "string",
    "countryCode": "string",
    "phone": "string",
    "email": "string",
    "website": "string",
    "taxNumber": "string",
    "vatId": "string",
    "smallBusiness": false,
    "commercialRegister": {
      "court": "string",
      "number": "string"
    },
    "bank": {
      "accountHolder": "string",
      "iban": "string",
      "bic": "string",
      "bankName": "string"
    },
    "invoiceFooter": "string"
  },
  "issueDate": "2026-11-01",
  "serviceDate": "2026-11-01",
  "servicePeriod": {
    "from": "2026-11-01",
    "to": "2026-11-01"
  },
  "serviceDateSource": "entered",
  "issuance": {
    "finalizedAt": "2026-11-01T09:30:00.000Z",
    "serverDate": "2026-11-01",
    "issueDate": "2026-11-01",
    "issueDateSource": "finalize_day",
    "deviationDays": 0,
    "reason": "string",
    "number": "string",
    "numberRange": "string"
  },
  "dueDate": "2026-11-01",
  "paymentTermsDays": 0,
  "priceMode": "net",
  "taxTreatment": "regular",
  "taxNotice": "string",
  "taxCase": {
    "facts": {
      "kind": "goods",
      "smallBusiness": false,
      "customerCountry": "string",
      "customerIsBusiness": false,
      "customerVatIdValid": false,
      "destinationCountry": null,
      "propertyCountry": null,
      "exemption": null
    },
    "treatment": "regular",
    "placeOfSupply": "string",
    "legalBasis": "string",
    "noticeVariant": "small_business",
    "ustvaKz": "string",
    "reporting": [
      "ustva"
    ],
    "confidence": "certain",
    "assumed": false,
    "reasons": [
      "string"
    ],
    "warnings": [
      "string"
    ]
  },
  "currency": "EUR",
  "subject": "string",
  "introText": "string",
  "closingText": "string",
  "reference": "string",
  "lines": [
    {
      "id": "string",
      "type": "item",
      "articleId": "string",
      "title": "string",
      "description": "string",
      "quantity": 1,
      "unit": "string",
      "unitPriceCents": 0,
      "discountPercent": 0,
      "taxRate": 19,
      "totalCents": 0,
      "servicePeriod": {
        "from": "2026-11-01",
        "to": "2026-11-01"
      },
      "projectId": "string",
      "timeEntryIds": [
        "string"
      ]
    }
  ],
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0,
    "groups": [
      {
        "taxRate": 0,
        "category": "string",
        "netCents": 0,
        "taxCents": 0,
        "grossCents": 0
      }
    ]
  },
  "deductions": [
    {
      "invoiceId": "string",
      "number": "string",
      "issueDate": "2026-11-01",
      "netCents": 0,
      "taxCents": 0,
      "grossCents": 0,
      "groups": [
        {
          "taxRate": null,
          "netCents": null,
          "taxCents": null
        }
      ],
      "invoiceGrossCents": 0,
      "unpaidCents": 0
    }
  ],
  "amountDueCents": 0,
  "paidCents": 0,
  "creditedCents": 0,
  "deductedCents": 0,
  "supersededCents": 0,
  "openCents": 0,
  "relatedInvoiceId": "string",
  "advanceInvoiceIds": [
    "string"
  ],
  "offerId": "string",
  "projectId": "string",
  "recurringInvoiceId": "string",
  "canceledByInvoiceId": "string",
  "debtId": "string",
  "showGiroCode": false,
  "einvoiceFormat": "none",
  "language": "de",
  "dispatch": {
    "count": 0,
    "lastChannel": "email",
    "lastSentAt": "2026-11-01T09:30:00.000Z"
  },
  "pdf": {
    "sha256": "string",
    "createdAt": "2026-11-01T09:30:00.000Z"
  },
  "locked": false,
  "lockedAt": "2026-11-01T09:30:00.000Z",
  "paidAt": "2026-11-01T09:30:00.000Z",
  "handedOverAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Update draft invoice

PATCH/api/v1/invoices/{id}

Only drafts can be changed. Finalised documents return 409 document_locked – make corrections with a credit note or cancellation. If lines is passed, it replaces all line items.

Permission: invoices:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Body (JSON) · InvoiceUpdate

kind"standard" | "advance" | "final"
standard = invoice, advance = progress invoice, final = final invoice
contactIdstring | null
Contact (customer) from /contacts
max. 128 characters
recipientDocumentRecipient
Recipient; if omitted, taken from the contact
- namestringrequired
  Company or name
  max. 160 characters
- additionstring
  Address supplement, e.g. attn. Ms Muster
  max. 160 characters
- streetstringrequired
  max. 160 characters · Default: ""
- zipCodestringrequired
  max. 10 characters · Default: ""
- citystringrequired
  max. 80 characters · Default: ""
- countrystringrequired
  Country code ISO 3166-1 alpha-2
  max. 2 characters · Default: "DE"
- emailstring (email)
  Invoice recipient (email)
  max. 254 characters
- vatIdstring
  Recipient's VAT ID (required for reverse charge/intra-Community supply)
- leitwegIdstring
  Leitweg-ID (XRechnung to public authorities)
  max. 60 characters
- einvoiceRecipientType"business" | "public_authority"
  E-invoice recipient profile (from the contact): public_authority requires a Leitweg-ID (ER-08)
- customerNumberstring
  Customer number (assigned on finalisation)
  max. 40 characters
issueDatestring (date) | null
Invoice date; empty = day of finalisation
serviceDatestring (date) | null
Delivery/service date
servicePeriodServicePeriod | null
Service period (instead of service date)
- fromstring (date)required
  Date (YYYY-MM-DD)
- tostring (date)required
  Date (YYYY-MM-DD)
dueDatestring (date) | null
Due date; empty = invoice date + payment term
paymentTermsDaysinteger
Payment term in days
0–365
priceMode"net" | "gross"
Unit prices net (B2B) or gross (B2C)
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"
Tax treatment of the receipt
subjectstring
Subject; empty = “Invoice <number>”
max. 200 characters
introTextstring
max. 5000 characters
closingTextstring
max. 5000 characters
referencestring
Customer's order number/reference
max. 100 characters
linesArray<DocumentLine>
- idstring
  stable line item ID (assigned by the server if empty)
  max. 40 characters
- type"item" | "text" | "subtotal"
  Line item, plain text line or subtotal
  Default: "item"
- articleIdstring
  Reference to the article master data
  max. 128 characters
- titlestringrequired
  max. 300 characters
- descriptionstring
  max. 5000 characters
- quantitynumber
  -1000000–1000000 · Default: 1
- unitstring
  Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
  max. 20 characters
- unitPriceCentsinteger
  Amount in cents
  -100000000000–100000000000 · Default: 0
- discountPercentnumber
  0–100
- taxRatenumber
  Tax rate in per cent (19, 7, 0 …)
  0–100 · Default: 19
- totalCentsinteger
  Amount in cents
  -100000000000–100000000000
- servicePeriodobject
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- projectIdstring
  max. 128 characters
- timeEntryIdsArray<string>
  max. 128 characters
relatedInvoiceIdstring | null
Credit note: corrected invoice
max. 128 characters
advanceInvoiceIdsArray<string>
Final invoice: progress invoices to deduct
max. 128 characters
offerIdstring | null
max. 128 characters
projectIdstring | null
max. 128 characters
showGiroCodeboolean
Print GiroCode (EPC QR) on the PDF
einvoiceFormat"none" | "zugferd" | "xrechnung"
E-invoice format (generation: E-invoice module)
taxFactsSaleTaxFacts | null
Facts for the tax assistant; the server derives the tax case from them (ST-16)
- kind"goods" | "service" | "construction" | "property_service" | "electronic_service"required
  Type of supply
- smallBusinessboolean
  own small-business status; if omitted, taken from Company & invoicing
- customerCountrystringrequired
  Country of residence of the recipient
  max. 2 characters
- customerIsBusinessbooleanrequired
  Recipient is a business and receives the supply for its business
- customerVatIdValidbooleanrequired
  a valid VAT ID of the recipient is available
- destinationCountrystring | null
  Supply of goods: country of destination
  max. 2 characters
- propertyCountrystring | null
  Service related to real estate: location of the property
  max. 2 characters
- exemption"§ 4 Nr. 8 UStG" | "§ 4 Nr. 11 UStG" | "§ 4 Nr. 12 UStG" | "§ 4 Nr. 14 UStG" | "§ 4 Nr. 21 UStG" | "other" | null
  VAT exemption without input VAT deduction
language"de" | "en" | null
Document language (PDF, email, free texts of the e-invoice); empty/null = the contact's language. Fixed on finalisation.

Response 200 · Invoice

idstringrequired
max. 128 characters
object"invoice"required
type"invoice" | "credit_note" | "cancellation"required
kind"standard" | "advance" | "final"required
status"draft" | "open" | "partially_paid" | "paid" | "overdue" | "canceled"required
numberstring | nullrequired
Document number; assigned only on finalising
contactIdstring | nullrequired
max. 128 characters
recipientDocumentRecipientrequired
- namestringrequired
  Company or name
  max. 160 characters
- additionstring
  Address supplement, e.g. attn. Ms Muster
  max. 160 characters
- streetstringrequired
  max. 160 characters · Default: ""
- zipCodestringrequired
  max. 10 characters · Default: ""
- citystringrequired
  max. 80 characters · Default: ""
- countrystringrequired
  Country code ISO 3166-1 alpha-2
  max. 2 characters · Default: "DE"
- emailstring (email)
  Invoice recipient (email)
  max. 254 characters
- vatIdstring
  Recipient's VAT ID (required for reverse charge/intra-Community supply)
- leitwegIdstring
  Leitweg-ID (XRechnung to public authorities)
  max. 60 characters
- einvoiceRecipientType"business" | "public_authority"
  E-invoice recipient profile (from the contact): public_authority requires a Leitweg-ID (ER-08)
- customerNumberstring
  Customer number (assigned on finalisation)
  max. 40 characters
senderSenderSnapshot | nullrequired
Sender snapshot (taken on finalising)
- companyNamestringrequired
- ownerNamestring
- legalFormstring
- managingDirectorsstring
- streetstringrequired
- zipCodestringrequired
- citystringrequired
- countryCodestringrequired
- phonestring
- emailstring
- websitestring
- taxNumberstring
- vatIdstring
- smallBusinessbooleanrequired
- commercialRegisterobject
  - courtstring
  - numberstring
- bankobject
  - accountHolderstring
  - ibanstring
  - bicstring
  - bankNamestring
- invoiceFooterstring
issueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
serviceDatestring (date) | nullrequired
Date (YYYY-MM-DD)
servicePeriodServicePeriod | nullrequired
- fromstring (date)required
  Date (YYYY-MM-DD)
- tostring (date)required
  Date (YYYY-MM-DD)
serviceDateSource"entered" | "period" | "confirmed_issue_date" | "recurring" | "not_applicable" | nullrequired
Source of the date of supply (ST-13): confirmed_issue_date = confirmed by the user
issuanceInvoiceIssuance | nullrequired
Evidence of issue (from finalising, ST-14)
- finalizedAtstring (date-time)required
  Server time of finalising
- serverDatestring (date)required
  Calendar day of finalising (Europe/Berlin)
- issueDatestring (date)required
  Date (YYYY-MM-DD)
- issueDateSource"finalize_day" | "entered"required
  finalize_day = day of finalising, entered = entered in the draft
- deviationDaysintegerrequired
  Issue date minus finalising day in days (negative = earlier)
  -9007199254740991–9007199254740991
- reasonstring | nullrequired
  Reason for a differing issue date
- numberstring | nullrequired
- numberRangestringrequired
  Number range
dueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
paymentTermsDaysintegerrequired
-9007199254740991–9007199254740991
priceMode"net" | "gross"required
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
Tax treatment of the receipt
taxNoticestring | nullrequired
Mandatory notice (§ 19, § 13b, intra-Community supply …)
taxCaseInvoiceTaxCase | nullrequired
Tax case (tax assistant); saved at the latest when finalising
- factsobjectrequired
  - kind"goods" | "service" | "construction" | "property_service" | "electronic_service"required
    Type of supply
  - smallBusinessbooleanrequired
  - customerCountrystringrequired
    Country of residence of the recipient
    max. 2 characters
  - customerIsBusinessbooleanrequired
    Recipient is a business and receives the supply for its business
  - customerVatIdValidbooleanrequired
    a valid VAT ID of the recipient is available
  - destinationCountrystring | null
    Supply of goods: country of destination
    max. 2 characters
  - propertyCountrystring | null
    Service related to real estate: location of the property
    max. 2 characters
  - exemption"§ 4 Nr. 8 UStG" | "§ 4 Nr. 11 UStG" | "§ 4 Nr. 12 UStG" | "§ 4 Nr. 14 UStG" | "§ 4 Nr. 21 UStG" | "other" | null
    VAT exemption without input VAT deduction
- treatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
  Tax treatment of the receipt
- placeOfSupplystringrequired
  Place of supply (ISO country)
- legalBasisstringrequired
- noticeVariantenum | nullrequired
  Case variant of the mandatory notice (ST-03)
  Values: small_business, reverse_charge, reverse_charge_eu, intra_eu_supply, export, non_taxable, tax_exempt
- ustvaKzstring | nullrequired
  Advance VAT return form field of the tax base (not for standard taxation)
- reportingArray<"ustva" | "zm" | "none">required
- confidence"certain" | "likely" | "review"required
- assumedbooleanrequired
  Facts assumed from the invoice data (not entered)
- reasonsArray<string>required
- warningsArray<string>required
currency"EUR"required
subjectstringrequired
introTextstringrequired
closingTextstringrequired
referencestringrequired
linesArray<DocumentLine>required
- idstring
  stable line item ID (assigned by the server if empty)
  max. 40 characters
- type"item" | "text" | "subtotal"
  Line item, plain text line or subtotal
  Default: "item"
- articleIdstring
  Reference to the article master data
  max. 128 characters
- titlestringrequired
  max. 300 characters
- descriptionstring
  max. 5000 characters
- quantitynumber
  -1000000–1000000 · Default: 1
- unitstring
  Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
  max. 20 characters
- unitPriceCentsinteger
  Amount in cents
  -100000000000–100000000000 · Default: 0
- discountPercentnumber
  0–100
- taxRatenumber
  Tax rate in per cent (19, 7, 0 …)
  0–100 · Default: 19
- totalCentsinteger
  Amount in cents
  -100000000000–100000000000
- servicePeriodobject
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- projectIdstring
  max. 128 characters
- timeEntryIdsArray<string>
  max. 128 characters
totalsDocumentTotalsrequired
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - categorystringrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
deductionsArray<InvoiceDeduction>required
Final invoice: advance payments actually received and deducted (ST-09)
- invoiceIdstringrequired
  max. 128 characters
- numberstringrequired
- issueDatestring (date)required
  Date (YYYY-MM-DD)
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
- invoiceGrossCentsinteger
  Invoice amount of the progress invoice (ST-09)
  -100000000000–100000000000
- unpaidCentsinteger
  Unreceived remainder of the progress invoice – not deducted (ST-09)
  -100000000000–100000000000
amountDueCentsintegerrequired
Amount payable (gross less progress invoices)
-100000000000–100000000000
paidCentsintegerrequired
Amount in cents
-100000000000–100000000000
creditedCentsintegerrequired
reduced by invoice corrections (progress invoice: incl. the remainder settled with the final invoice)
-100000000000–100000000000
deductedCentsinteger | nullrequired
Progress invoice: amount received and deducted in the final invoice (ST-09)
-100000000000–100000000000
supersededCentsinteger | nullrequired
Progress invoice: unpaid remainder settled with the final invoice (ST-09)
-100000000000–100000000000
openCentsintegerrequired
Amount in cents
-100000000000–100000000000
relatedInvoiceIdstring | nullrequired
max. 128 characters
advanceInvoiceIdsArray<string>required
max. 128 characters
offerIdstring | nullrequired
max. 128 characters
projectIdstring | nullrequired
max. 128 characters
recurringInvoiceIdstring | nullrequired
max. 128 characters
canceledByInvoiceIdstring | nullrequired
Cancellation invoice for this invoice
max. 128 characters
debtIdstring | nullrequired
Debt in dunning (after handover)
max. 128 characters
showGiroCodebooleanrequired
einvoiceFormat"none" | "zugferd" | "xrechnung"required
language"de" | "en"required
Document language (fixed on finalisation)
dispatchobjectrequired
- countintegerrequired
  -9007199254740991–9007199254740991
- lastChannel"email" | "post" | nullrequired
- lastSentAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
pdfobject | nullrequired
archived PDF (after finalisation)
- sha256stringrequired
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
lockedbooleanrequired
lockedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
paidAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
handedOverAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 429, 500

curl -X PATCH 'https://www.debt-flow.io/api/v1/invoices/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "kind": "standard",
  "contactId": "string",
  "recipient": {
    "name": "string",
    "addition": "string",
    "street": "",
    "zipCode": "",
    "city": "",
    "country": "DE",
    "email": "[email protected]",
    "vatId": "string",
    "leitwegId": "string",
    "einvoiceRecipientType": "business",
    "customerNumber": "string"
  },
  "issueDate": "2026-11-01",
  "serviceDate": "2026-11-01",
  "servicePeriod": {
    "from": "2026-11-01",
    "to": "2026-11-01"
  },
  "dueDate": "2026-11-01",
  "paymentTermsDays": 0,
  "priceMode": "net",
  "taxTreatment": "regular",
  "subject": "string",
  "introText": "string",
  "closingText": "string",
  "reference": "string",
  "lines": [
    {
      "id": "string",
      "type": "item",
      "articleId": "string",
      "title": "string",
      "description": "string",
      "quantity": 1,
      "unit": "string",
      "unitPriceCents": 0,
      "discountPercent": 0,
      "taxRate": 19,
      "totalCents": 0,
      "servicePeriod": {
        "from": "2026-11-01",
        "to": "2026-11-01"
      },
      "projectId": "string",
      "timeEntryIds": [
        "string"
      ]
    }
  ],
  "relatedInvoiceId": "string",
  "advanceInvoiceIds": [
    "string"
  ],
  "offerId": "string",
  "projectId": "string",
  "showGiroCode": false,
  "einvoiceFormat": "none",
  "taxFacts": {
    "kind": "goods",
    "smallBusiness": false,
    "customerCountry": "string",
    "customerIsBusiness": false,
    "customerVatIdValid": false,
    "destinationCountry": "string",
    "propertyCountry": "string",
    "exemption": "§ 4 Nr. 8 UStG"
  },
  "language": "de"
}'

Response 200

{
  "id": "string",
  "object": "invoice",
  "type": "invoice",
  "kind": "standard",
  "status": "draft",
  "number": "string",
  "contactId": "string",
  "recipient": {
    "name": "string",
    "addition": "string",
    "street": "",
    "zipCode": "",
    "city": "",
    "country": "DE",
    "email": "[email protected]",
    "vatId": "string",
    "leitwegId": "string",
    "einvoiceRecipientType": "business",
    "customerNumber": "string"
  },
  "sender": {
    "companyName": "string",
    "ownerName": "string",
    "legalForm": "string",
    "managingDirectors": "string",
    "street": "string",
    "zipCode": "string",
    "city": "string",
    "countryCode": "string",
    "phone": "string",
    "email": "string",
    "website": "string",
    "taxNumber": "string",
    "vatId": "string",
    "smallBusiness": false,
    "commercialRegister": {
      "court": "string",
      "number": "string"
    },
    "bank": {
      "accountHolder": "string",
      "iban": "string",
      "bic": "string",
      "bankName": "string"
    },
    "invoiceFooter": "string"
  },
  "issueDate": "2026-11-01",
  "serviceDate": "2026-11-01",
  "servicePeriod": {
    "from": "2026-11-01",
    "to": "2026-11-01"
  },
  "serviceDateSource": "entered",
  "issuance": {
    "finalizedAt": "2026-11-01T09:30:00.000Z",
    "serverDate": "2026-11-01",
    "issueDate": "2026-11-01",
    "issueDateSource": "finalize_day",
    "deviationDays": 0,
    "reason": "string",
    "number": "string",
    "numberRange": "string"
  },
  "dueDate": "2026-11-01",
  "paymentTermsDays": 0,
  "priceMode": "net",
  "taxTreatment": "regular",
  "taxNotice": "string",
  "taxCase": {
    "facts": {
      "kind": "goods",
      "smallBusiness": false,
      "customerCountry": "string",
      "customerIsBusiness": false,
      "customerVatIdValid": false,
      "destinationCountry": null,
      "propertyCountry": null,
      "exemption": null
    },
    "treatment": "regular",
    "placeOfSupply": "string",
    "legalBasis": "string",
    "noticeVariant": "small_business",
    "ustvaKz": "string",
    "reporting": [
      "ustva"
    ],
    "confidence": "certain",
    "assumed": false,
    "reasons": [
      "string"
    ],
    "warnings": [
      "string"
    ]
  },
  "currency": "EUR",
  "subject": "string",
  "introText": "string",
  "closingText": "string",
  "reference": "string",
  "lines": [
    {
      "id": "string",
      "type": "item",
      "articleId": "string",
      "title": "string",
      "description": "string",
      "quantity": 1,
      "unit": "string",
      "unitPriceCents": 0,
      "discountPercent": 0,
      "taxRate": 19,
      "totalCents": 0,
      "servicePeriod": {
        "from": "2026-11-01",
        "to": "2026-11-01"
      },
      "projectId": "string",
      "timeEntryIds": [
        "string"
      ]
    }
  ],
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0,
    "groups": [
      {
        "taxRate": 0,
        "category": "string",
        "netCents": 0,
        "taxCents": 0,
        "grossCents": 0
      }
    ]
  },
  "deductions": [
    {
      "invoiceId": "string",
      "number": "string",
      "issueDate": "2026-11-01",
      "netCents": 0,
      "taxCents": 0,
      "grossCents": 0,
      "groups": [
        {
          "taxRate": null,
          "netCents": null,
          "taxCents": null
        }
      ],
      "invoiceGrossCents": 0,
      "unpaidCents": 0
    }
  ],
  "amountDueCents": 0,
  "paidCents": 0,
  "creditedCents": 0,
  "deductedCents": 0,
  "supersededCents": 0,
  "openCents": 0,
  "relatedInvoiceId": "string",
  "advanceInvoiceIds": [
    "string"
  ],
  "offerId": "string",
  "projectId": "string",
  "recurringInvoiceId": "string",
  "canceledByInvoiceId": "string",
  "debtId": "string",
  "showGiroCode": false,
  "einvoiceFormat": "none",
  "language": "de",
  "dispatch": {
    "count": 0,
    "lastChannel": "email",
    "lastSentAt": "2026-11-01T09:30:00.000Z"
  },
  "pdf": {
    "sha256": "string",
    "createdAt": "2026-11-01T09:30:00.000Z"
  },
  "locked": false,
  "lockedAt": "2026-11-01T09:30:00.000Z",
  "paidAt": "2026-11-01T09:30:00.000Z",
  "handedOverAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Delete draft invoice

DELETE/api/v1/invoices/{id}

Drafts only. Finalised documents are retained (GoBD).

Permission: invoices:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Response 204

Success, no content

Possible errors: 400, 401, 403, 404, 409, 429, 500

curl -X DELETE 'https://www.debt-flow.io/api/v1/invoices/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Audit log of an invoice

GET/api/v1/invoices/{id}/audit-log

All changes (GoBD) with actor, timestamp, changed fields and hash of the log chain.

Permission: invoices:read

Path parameters

idstringrequired
Resource ID
max. 128 characters

Query parameters

limitinteger
Number of entries (1–100)
1–100 · Default: 25
cursorstring
`nextCursor` of the previous page
max. 500 characters

Response 200

object"list"required
dataArray<AuditEntry>required
- idstringrequired
  sequence number in the audit log
- seqintegerrequired
  -9007199254740991–9007199254740991
- atstring (date-time)required
  Timestamp (ISO 8601)
- actorActorrequired
  - type"user" | "api_key" | "oauth" | "system"required
  - idstringrequired
  - labelstring
- actionstringrequired
- changesobjectrequired
- metaobject | nullrequired
- hashstringrequired
hasMorebooleanrequired
nextCursorstring | nullrequired

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/invoices/ID/audit-log' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "seq": 0,
      "at": "2026-11-01T09:30:00.000Z",
      "actor": {
        "type": "user",
        "id": "string",
        "label": "string"
      },
      "action": "string",
      "changes": {},
      "meta": {},
      "hash": "string"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Cancel invoice

POST/api/v1/invoices/{id}/cancel

Creates and finalises a cancellation invoice for the full amount (number range for credit notes/cancellations) and sets the invoice to canceled. Amounts already paid appear on the cancellation invoice as the amount to be refunded. If credit notes exist: 409.

Permission: invoices:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Headers

Idempotency-Keystring
Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
max. 255 characters

Body (JSON) · InvoiceCancel

reasonstring
Reason (shown on the cancellation invoice)
max. 500 characters
issueDatestring (date)
Date of the cancellation invoice; default today
issueDateReasonstring
Reason if the cancellation date is not today (ST-14)
max. 500 characters

Response 201 · InvoiceCancelResult

invoiceInvoicerequired
- idstringrequired
  max. 128 characters
- object"invoice"required
- type"invoice" | "credit_note" | "cancellation"required
- kind"standard" | "advance" | "final"required
- status"draft" | "open" | "partially_paid" | "paid" | "overdue" | "canceled"required
- numberstring | nullrequired
  Document number; assigned only on finalising
- contactIdstring | nullrequired
  max. 128 characters
- recipientDocumentRecipientrequired
  - namestringrequired
    Company or name
    max. 160 characters
  - additionstring
    Address supplement, e.g. attn. Ms Muster
    max. 160 characters
  - streetstringrequired
    max. 160 characters · Default: ""
  - zipCodestringrequired
    max. 10 characters · Default: ""
  - citystringrequired
    max. 80 characters · Default: ""
  - countrystringrequired
    Country code ISO 3166-1 alpha-2
    max. 2 characters · Default: "DE"
  - emailstring (email)
    Invoice recipient (email)
    max. 254 characters
  - vatIdstring
    Recipient's VAT ID (required for reverse charge/intra-Community supply)
  - leitwegIdstring
    Leitweg-ID (XRechnung to public authorities)
    max. 60 characters
  - einvoiceRecipientType"business" | "public_authority"
    E-invoice recipient profile (from the contact): public_authority requires a Leitweg-ID (ER-08)
  - customerNumberstring
    Customer number (assigned on finalisation)
    max. 40 characters
- senderSenderSnapshot | nullrequired
  Sender snapshot (taken on finalising)
  - companyNamestringrequired
  - ownerNamestring
  - legalFormstring
  - managingDirectorsstring
  - streetstringrequired
  - zipCodestringrequired
  - citystringrequired
  - countryCodestringrequired
  - phonestring
  - emailstring
  - websitestring
  - taxNumberstring
  - vatIdstring
  - smallBusinessbooleanrequired
  - commercialRegisterobject
  - bankobject
  - invoiceFooterstring
- issueDatestring (date) | nullrequired
  Date (YYYY-MM-DD)
- serviceDatestring (date) | nullrequired
  Date (YYYY-MM-DD)
- servicePeriodServicePeriod | nullrequired
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- serviceDateSource"entered" | "period" | "confirmed_issue_date" | "recurring" | "not_applicable" | nullrequired
  Source of the date of supply (ST-13): confirmed_issue_date = confirmed by the user
- issuanceInvoiceIssuance | nullrequired
  Evidence of issue (from finalising, ST-14)
  - finalizedAtstring (date-time)required
    Server time of finalising
  - serverDatestring (date)required
    Calendar day of finalising (Europe/Berlin)
  - issueDatestring (date)required
    Date (YYYY-MM-DD)
  - issueDateSource"finalize_day" | "entered"required
    finalize_day = day of finalising, entered = entered in the draft
  - deviationDaysintegerrequired
    Issue date minus finalising day in days (negative = earlier)
    -9007199254740991–9007199254740991
  - reasonstring | nullrequired
    Reason for a differing issue date
  - numberstring | nullrequired
  - numberRangestringrequired
    Number range
- dueDatestring (date) | nullrequired
  Date (YYYY-MM-DD)
- paymentTermsDaysintegerrequired
  -9007199254740991–9007199254740991
- priceMode"net" | "gross"required
- taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
  Tax treatment of the receipt
- taxNoticestring | nullrequired
  Mandatory notice (§ 19, § 13b, intra-Community supply …)
- taxCaseInvoiceTaxCase | nullrequired
  Tax case (tax assistant); saved at the latest when finalising
  - factsobjectrequired
  - treatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
    Tax treatment of the receipt
  - placeOfSupplystringrequired
    Place of supply (ISO country)
  - legalBasisstringrequired
  - noticeVariantenum | nullrequired
    Case variant of the mandatory notice (ST-03)
    Values: small_business, reverse_charge, reverse_charge_eu, intra_eu_supply, export, non_taxable, tax_exempt
  - ustvaKzstring | nullrequired
    Advance VAT return form field of the tax base (not for standard taxation)
  - reportingArray<"ustva" | "zm" | "none">required
  - confidence"certain" | "likely" | "review"required
  - assumedbooleanrequired
    Facts assumed from the invoice data (not entered)
  - reasonsArray<string>required
  - warningsArray<string>required
- currency"EUR"required
- subjectstringrequired
- introTextstringrequired
- closingTextstringrequired
- referencestringrequired
- linesArray<DocumentLine>required
  - idstring
    stable line item ID (assigned by the server if empty)
    max. 40 characters
  - type"item" | "text" | "subtotal"
    Line item, plain text line or subtotal
    Default: "item"
  - articleIdstring
    Reference to the article master data
    max. 128 characters
  - titlestringrequired
    max. 300 characters
  - descriptionstring
    max. 5000 characters
  - quantitynumber
    -1000000–1000000 · Default: 1
  - unitstring
    Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
    max. 20 characters
  - unitPriceCentsinteger
    Amount in cents
    -100000000000–100000000000 · Default: 0
  - discountPercentnumber
    0–100
  - taxRatenumber
    Tax rate in per cent (19, 7, 0 …)
    0–100 · Default: 19
  - totalCentsinteger
    Amount in cents
    -100000000000–100000000000
  - servicePeriodobject
  - projectIdstring
    max. 128 characters
  - timeEntryIdsArray<string>
    max. 128 characters
- totalsDocumentTotalsrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - groupsArray<object>required
- deductionsArray<InvoiceDeduction>required
  Final invoice: advance payments actually received and deducted (ST-09)
  - invoiceIdstringrequired
    max. 128 characters
  - numberstringrequired
  - issueDatestring (date)required
    Date (YYYY-MM-DD)
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - groupsArray<object>required
  - invoiceGrossCentsinteger
    Invoice amount of the progress invoice (ST-09)
    -100000000000–100000000000
  - unpaidCentsinteger
    Unreceived remainder of the progress invoice – not deducted (ST-09)
    -100000000000–100000000000
- amountDueCentsintegerrequired
  Amount payable (gross less progress invoices)
  -100000000000–100000000000
- paidCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- creditedCentsintegerrequired
  reduced by invoice corrections (progress invoice: incl. the remainder settled with the final invoice)
  -100000000000–100000000000
- deductedCentsinteger | nullrequired
  Progress invoice: amount received and deducted in the final invoice (ST-09)
  -100000000000–100000000000
- supersededCentsinteger | nullrequired
  Progress invoice: unpaid remainder settled with the final invoice (ST-09)
  -100000000000–100000000000
- openCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- relatedInvoiceIdstring | nullrequired
  max. 128 characters
- advanceInvoiceIdsArray<string>required
  max. 128 characters
- offerIdstring | nullrequired
  max. 128 characters
- projectIdstring | nullrequired
  max. 128 characters
- recurringInvoiceIdstring | nullrequired
  max. 128 characters
- canceledByInvoiceIdstring | nullrequired
  Cancellation invoice for this invoice
  max. 128 characters
- debtIdstring | nullrequired
  Debt in dunning (after handover)
  max. 128 characters
- showGiroCodebooleanrequired
- einvoiceFormat"none" | "zugferd" | "xrechnung"required
- language"de" | "en"required
  Document language (fixed on finalisation)
- dispatchobjectrequired
  - countintegerrequired
    -9007199254740991–9007199254740991
  - lastChannel"email" | "post" | nullrequired
  - lastSentAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
- pdfobject | nullrequired
  archived PDF (after finalisation)
  - sha256stringrequired
  - createdAtstring (date-time)required
    Timestamp (ISO 8601)
- lockedbooleanrequired
- lockedAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
- paidAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
- handedOverAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
- updatedAtstring (date-time)required
  Timestamp (ISO 8601)
cancellationInvoicerequired
finalised cancellation invoice
- idstringrequired
  max. 128 characters
- object"invoice"required
- type"invoice" | "credit_note" | "cancellation"required
- kind"standard" | "advance" | "final"required
- status"draft" | "open" | "partially_paid" | "paid" | "overdue" | "canceled"required
- numberstring | nullrequired
  Document number; assigned only on finalising
- contactIdstring | nullrequired
  max. 128 characters
- recipientDocumentRecipientrequired
  - namestringrequired
    Company or name
    max. 160 characters
  - additionstring
    Address supplement, e.g. attn. Ms Muster
    max. 160 characters
  - streetstringrequired
    max. 160 characters · Default: ""
  - zipCodestringrequired
    max. 10 characters · Default: ""
  - citystringrequired
    max. 80 characters · Default: ""
  - countrystringrequired
    Country code ISO 3166-1 alpha-2
    max. 2 characters · Default: "DE"
  - emailstring (email)
    Invoice recipient (email)
    max. 254 characters
  - vatIdstring
    Recipient's VAT ID (required for reverse charge/intra-Community supply)
  - leitwegIdstring
    Leitweg-ID (XRechnung to public authorities)
    max. 60 characters
  - einvoiceRecipientType"business" | "public_authority"
    E-invoice recipient profile (from the contact): public_authority requires a Leitweg-ID (ER-08)
  - customerNumberstring
    Customer number (assigned on finalisation)
    max. 40 characters
- senderSenderSnapshot | nullrequired
  Sender snapshot (taken on finalising)
  - companyNamestringrequired
  - ownerNamestring
  - legalFormstring
  - managingDirectorsstring
  - streetstringrequired
  - zipCodestringrequired
  - citystringrequired
  - countryCodestringrequired
  - phonestring
  - emailstring
  - websitestring
  - taxNumberstring
  - vatIdstring
  - smallBusinessbooleanrequired
  - commercialRegisterobject
  - bankobject
  - invoiceFooterstring
- issueDatestring (date) | nullrequired
  Date (YYYY-MM-DD)
- serviceDatestring (date) | nullrequired
  Date (YYYY-MM-DD)
- servicePeriodServicePeriod | nullrequired
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- serviceDateSource"entered" | "period" | "confirmed_issue_date" | "recurring" | "not_applicable" | nullrequired
  Source of the date of supply (ST-13): confirmed_issue_date = confirmed by the user
- issuanceInvoiceIssuance | nullrequired
  Evidence of issue (from finalising, ST-14)
  - finalizedAtstring (date-time)required
    Server time of finalising
  - serverDatestring (date)required
    Calendar day of finalising (Europe/Berlin)
  - issueDatestring (date)required
    Date (YYYY-MM-DD)
  - issueDateSource"finalize_day" | "entered"required
    finalize_day = day of finalising, entered = entered in the draft
  - deviationDaysintegerrequired
    Issue date minus finalising day in days (negative = earlier)
    -9007199254740991–9007199254740991
  - reasonstring | nullrequired
    Reason for a differing issue date
  - numberstring | nullrequired
  - numberRangestringrequired
    Number range
- dueDatestring (date) | nullrequired
  Date (YYYY-MM-DD)
- paymentTermsDaysintegerrequired
  -9007199254740991–9007199254740991
- priceMode"net" | "gross"required
- taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
  Tax treatment of the receipt
- taxNoticestring | nullrequired
  Mandatory notice (§ 19, § 13b, intra-Community supply …)
- taxCaseInvoiceTaxCase | nullrequired
  Tax case (tax assistant); saved at the latest when finalising
  - factsobjectrequired
  - treatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
    Tax treatment of the receipt
  - placeOfSupplystringrequired
    Place of supply (ISO country)
  - legalBasisstringrequired
  - noticeVariantenum | nullrequired
    Case variant of the mandatory notice (ST-03)
    Values: small_business, reverse_charge, reverse_charge_eu, intra_eu_supply, export, non_taxable, tax_exempt
  - ustvaKzstring | nullrequired
    Advance VAT return form field of the tax base (not for standard taxation)
  - reportingArray<"ustva" | "zm" | "none">required
  - confidence"certain" | "likely" | "review"required
  - assumedbooleanrequired
    Facts assumed from the invoice data (not entered)
  - reasonsArray<string>required
  - warningsArray<string>required
- currency"EUR"required
- subjectstringrequired
- introTextstringrequired
- closingTextstringrequired
- referencestringrequired
- linesArray<DocumentLine>required
  - idstring
    stable line item ID (assigned by the server if empty)
    max. 40 characters
  - type"item" | "text" | "subtotal"
    Line item, plain text line or subtotal
    Default: "item"
  - articleIdstring
    Reference to the article master data
    max. 128 characters
  - titlestringrequired
    max. 300 characters
  - descriptionstring
    max. 5000 characters
  - quantitynumber
    -1000000–1000000 · Default: 1
  - unitstring
    Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
    max. 20 characters
  - unitPriceCentsinteger
    Amount in cents
    -100000000000–100000000000 · Default: 0
  - discountPercentnumber
    0–100
  - taxRatenumber
    Tax rate in per cent (19, 7, 0 …)
    0–100 · Default: 19
  - totalCentsinteger
    Amount in cents
    -100000000000–100000000000
  - servicePeriodobject
  - projectIdstring
    max. 128 characters
  - timeEntryIdsArray<string>
    max. 128 characters
- totalsDocumentTotalsrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - groupsArray<object>required
- deductionsArray<InvoiceDeduction>required
  Final invoice: advance payments actually received and deducted (ST-09)
  - invoiceIdstringrequired
    max. 128 characters
  - numberstringrequired
  - issueDatestring (date)required
    Date (YYYY-MM-DD)
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - groupsArray<object>required
  - invoiceGrossCentsinteger
    Invoice amount of the progress invoice (ST-09)
    -100000000000–100000000000
  - unpaidCentsinteger
    Unreceived remainder of the progress invoice – not deducted (ST-09)
    -100000000000–100000000000
- amountDueCentsintegerrequired
  Amount payable (gross less progress invoices)
  -100000000000–100000000000
- paidCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- creditedCentsintegerrequired
  reduced by invoice corrections (progress invoice: incl. the remainder settled with the final invoice)
  -100000000000–100000000000
- deductedCentsinteger | nullrequired
  Progress invoice: amount received and deducted in the final invoice (ST-09)
  -100000000000–100000000000
- supersededCentsinteger | nullrequired
  Progress invoice: unpaid remainder settled with the final invoice (ST-09)
  -100000000000–100000000000
- openCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- relatedInvoiceIdstring | nullrequired
  max. 128 characters
- advanceInvoiceIdsArray<string>required
  max. 128 characters
- offerIdstring | nullrequired
  max. 128 characters
- projectIdstring | nullrequired
  max. 128 characters
- recurringInvoiceIdstring | nullrequired
  max. 128 characters
- canceledByInvoiceIdstring | nullrequired
  Cancellation invoice for this invoice
  max. 128 characters
- debtIdstring | nullrequired
  Debt in dunning (after handover)
  max. 128 characters
- showGiroCodebooleanrequired
- einvoiceFormat"none" | "zugferd" | "xrechnung"required
- language"de" | "en"required
  Document language (fixed on finalisation)
- dispatchobjectrequired
  - countintegerrequired
    -9007199254740991–9007199254740991
  - lastChannel"email" | "post" | nullrequired
  - lastSentAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
- pdfobject | nullrequired
  archived PDF (after finalisation)
  - sha256stringrequired
  - createdAtstring (date-time)required
    Timestamp (ISO 8601)
- lockedbooleanrequired
- lockedAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
- paidAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
- handedOverAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
- updatedAtstring (date-time)required
  Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/invoices/ID/cancel' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "reason": "string",
  "issueDate": "2026-11-01",
  "issueDateReason": "string"
}'

Response 201

{
  "invoice": {
    "id": "string",
    "object": "invoice",
    "type": "invoice",
    "kind": "standard",
    "status": "draft",
    "number": "string",
    "contactId": "string",
    "recipient": {
      "name": "string",
      "addition": "string",
      "street": "",
      "zipCode": "",
      "city": "",
      "country": "DE",
      "email": "[email protected]",
      "vatId": "string",
      "leitwegId": "string",
      "einvoiceRecipientType": "business",
      "customerNumber": "string"
    },
    "sender": {
      "companyName": null,
      "ownerName": null,
      "legalForm": null,
      "managingDirectors": null,
      "street": null,
      "zipCode": null,
      "city": null,
      "countryCode": null,
      "phone": null,
      "email": null,
      "website": null,
      "taxNumber": null,
      "vatId": null,
      "smallBusiness": null,
      "commercialRegister": null,
      "bank": null,
      "invoiceFooter": null
    },
    "issueDate": "2026-11-01",
    "serviceDate": "2026-11-01",
    "servicePeriod": {
      "from": null,
      "to": null
    },
    "serviceDateSource": "entered",
    "issuance": {
      "finalizedAt": null,
      "serverDate": null,
      "issueDate": null,
      "issueDateSource": null,
      "deviationDays": null,
      "reason": null,
      "number": null,
      "numberRange": null
    },
    "dueDate": "2026-11-01",
    "paymentTermsDays": 0,
    "priceMode": "net",
    "taxTreatment": "regular",
    "taxNotice": "string",
    "taxCase": {
      "facts": null,
      "treatment": null,
      "placeOfSupply": null,
      "legalBasis": null,
      "noticeVariant": null,
      "ustvaKz": null,
      "reporting": null,
      "confidence": null,
      "assumed": null,
      "reasons": null,
      "warnings": null
    },
    "currency": "EUR",
    "subject": "string",
    "introText": "string",
    "closingText": "string",
    "reference": "string",
    "lines": [
      {
        "id": null,
        "type": null,
        "articleId": null,
        "title": null,
        "description": null,
        "quantity": null,
        "unit": null,
        "unitPriceCents": null,
        "discountPercent": null,
        "taxRate": null,
        "totalCents": null,
        "servicePeriod": null,
        "projectId": null,
        "timeEntryIds": null
      }
    ],
    "totals": {
      "netCents": 0,
      "taxCents": 0,
      "grossCents": 0,
      "groups": [
        null
      ]
    },
    "deductions": [
      {
        "invoiceId": null,
        "number": null,
        "issueDate": null,
        "netCents": null,
        "taxCents": null,
        "grossCents": null,
        "groups": null,
        "invoiceGrossCents": null,
        "unpaidCents": null
      }
    ],
    "amountDueCents": 0,
    "paidCents": 0,
    "creditedCents": 0,
    "deductedCents": 0,
    "supersededCents": 0,
    "openCents": 0,
    "relatedInvoiceId": "string",
    "advanceInvoiceIds": [
      "string"
    ],
    "offerId": "string",
    "projectId": "string",
    "recurringInvoiceId": "string",
    "canceledByInvoiceId": "string",
    "debtId": "string",
    "showGiroCode": false,
    "einvoiceFormat": "none",
    "language": "de",
    "dispatch": {
      "count": 0,
      "lastChannel": "email",
      "lastSentAt": "2026-11-01T09:30:00.000Z"
    },
    "pdf": {
      "sha256": "string",
      "createdAt": "2026-11-01T09:30:00.000Z"
    },
    "locked": false,
    "lockedAt": "2026-11-01T09:30:00.000Z",
    "paidAt": "2026-11-01T09:30:00.000Z",
    "handedOverAt": "2026-11-01T09:30:00.000Z",
    "createdAt": "2026-11-01T09:30:00.000Z",
    "updatedAt": "2026-11-01T09:30:00.000Z"
  },
  "cancellation": {
    "id": "string",
    "object": "invoice",
    "type": "invoice",
    "kind": "standard",
    "status": "draft",
    "number": "string",
    "contactId": "string",
    "recipient": {
      "name": "string",
      "addition": "string",
      "street": "",
      "zipCode": "",
      "city": "",
      "country": "DE",
      "email": "[email protected]",
      "vatId": "string",
      "leitwegId": "string",
      "einvoiceRecipientType": "business",
      "customerNumber": "string"
    },
    "sender": {
      "companyName": null,
      "ownerName": null,
      "legalForm": null,
      "managingDirectors": null,
      "street": null,
      "zipCode": null,
      "city": null,
      "countryCode": null,
      "phone": null,
      "email": null,
      "website": null,
      "taxNumber": null,
      "vatId": null,
      "smallBusiness": null,
      "commercialRegister": null,
      "bank": null,
      "invoiceFooter": null
    },
    "issueDate": "2026-11-01",
    "serviceDate": "2026-11-01",
    "servicePeriod": {
      "from": null,
      "to": null
    },
    "serviceDateSource": "entered",
    "issuance": {
      "finalizedAt": null,
      "serverDate": null,
      "issueDate": null,
      "issueDateSource": null,
      "deviationDays": null,
      "reason": null,
      "number": null,
      "numberRange": null
    },
    "dueDate": "2026-11-01",
    "paymentTermsDays": 0,
    "priceMode": "net",
    "taxTreatment": "regular",
    "taxNotice": "string",
    "taxCase": {
      "facts": null,
      "treatment": null,
      "placeOfSupply": null,
      "legalBasis": null,
      "noticeVariant": null,
      "ustvaKz": null,
      "reporting": null,
      "confidence": null,
      "assumed": null,
      "reasons": null,
      "warnings": null
    },
    "currency": "EUR",
    "subject": "string",
    "introText": "string",
    "closingText": "string",
    "reference": "string",
    "lines": [
      {
        "id": null,
        "type": null,
        "articleId": null,
        "title": null,
        "description": null,
        "quantity": null,
        "unit": null,
        "unitPriceCents": null,
        "discountPercent": null,
        "taxRate": null,
        "totalCents": null,
        "servicePeriod": null,
        "projectId": null,
        "timeEntryIds": null
      }
    ],
    "totals": {
      "netCents": 0,
      "taxCents": 0,
      "grossCents": 0,
      "groups": [
        null
      ]
    },
    "deductions": [
      {
        "invoiceId": null,
        "number": null,
        "issueDate": null,
        "netCents": null,
        "taxCents": null,
        "grossCents": null,
        "groups": null,
        "invoiceGrossCents": null,
        "unpaidCents": null
      }
    ],
    "amountDueCents": 0,
    "paidCents": 0,
    "creditedCents": 0,
    "deductedCents": 0,
    "supersededCents": 0,
    "openCents": 0,
    "relatedInvoiceId": "string",
    "advanceInvoiceIds": [
      "string"
    ],
    "offerId": "string",
    "projectId": "string",
    "recurringInvoiceId": "string",
    "canceledByInvoiceId": "string",
    "debtId": "string",
    "showGiroCode": false,
    "einvoiceFormat": "none",
    "language": "de",
    "dispatch": {
      "count": 0,
      "lastChannel": "email",
      "lastSentAt": "2026-11-01T09:30:00.000Z"
    },
    "pdf": {
      "sha256": "string",
      "createdAt": "2026-11-01T09:30:00.000Z"
    },
    "locked": false,
    "lockedAt": "2026-11-01T09:30:00.000Z",
    "paidAt": "2026-11-01T09:30:00.000Z",
    "handedOverAt": "2026-11-01T09:30:00.000Z",
    "createdAt": "2026-11-01T09:30:00.000Z",
    "updatedAt": "2026-11-01T09:30:00.000Z"
  }
}

Dispatch log of an invoice

GET/api/v1/invoices/{id}/dispatches

Permission: invoices:read

Path parameters

idstringrequired
Resource ID
max. 128 characters

Query parameters

limitinteger
Number of entries (1–100)
1–100 · Default: 25
cursorstring
`nextCursor` of the previous page
max. 500 characters

Response 200

object"list"required
dataArray<InvoiceDispatch>required
- idstringrequired
  max. 128 characters
- invoiceIdstringrequired
  max. 128 characters
- channel"email" | "post"required
- status"sending" | "sent" | "failed"required
- toArray<string>required
- subjectstring | nullrequired
- registeredbooleanrequired
- letterIdstring | nullrequired
- trackingRefstring | nullrequired
- pageCountinteger | nullrequired
  -9007199254740991–9007199254740991
- priceEurostring | nullrequired
- deliveryStatus"pending" | "delivered" | "failed" | "returned" | nullrequired
  Post only: delivery status according to Briefdiener (cron letter-status), otherwise null
- deliveryMessagestring | nullrequired
- trackingUrlstring | nullrequired
- deliveryUpdatedAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
- errorstring | nullrequired
- actorActor | nullrequired
  - type"user" | "api_key" | "oauth" | "system"required
  - idstringrequired
  - labelstring
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
- sentAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
hasMorebooleanrequired
nextCursorstring | nullrequired

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/invoices/ID/dispatches' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "invoiceId": "string",
      "channel": "email",
      "status": "sending",
      "to": [
        "string"
      ],
      "subject": "string",
      "registered": false,
      "letterId": "string",
      "trackingRef": "string",
      "pageCount": 0,
      "priceEuro": "string",
      "deliveryStatus": "pending",
      "deliveryMessage": "string",
      "trackingUrl": "string",
      "deliveryUpdatedAt": "2026-11-01T09:30:00.000Z",
      "error": "string",
      "actor": {
        "type": null,
        "id": null,
        "label": null
      },
      "createdAt": "2026-11-01T09:30:00.000Z",
      "sentAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Copy invoice as new draft

POST/api/v1/invoices/{id}/duplicate

Copies the customer, texts and line items into a new draft (without number and date).

Permission: invoices:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Headers

Idempotency-Keystring
Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
max. 255 characters

Response 201 · Invoice

idstringrequired
max. 128 characters
object"invoice"required
type"invoice" | "credit_note" | "cancellation"required
kind"standard" | "advance" | "final"required
status"draft" | "open" | "partially_paid" | "paid" | "overdue" | "canceled"required
numberstring | nullrequired
Document number; assigned only on finalising
contactIdstring | nullrequired
max. 128 characters
recipientDocumentRecipientrequired
- namestringrequired
  Company or name
  max. 160 characters
- additionstring
  Address supplement, e.g. attn. Ms Muster
  max. 160 characters
- streetstringrequired
  max. 160 characters · Default: ""
- zipCodestringrequired
  max. 10 characters · Default: ""
- citystringrequired
  max. 80 characters · Default: ""
- countrystringrequired
  Country code ISO 3166-1 alpha-2
  max. 2 characters · Default: "DE"
- emailstring (email)
  Invoice recipient (email)
  max. 254 characters
- vatIdstring
  Recipient's VAT ID (required for reverse charge/intra-Community supply)
- leitwegIdstring
  Leitweg-ID (XRechnung to public authorities)
  max. 60 characters
- einvoiceRecipientType"business" | "public_authority"
  E-invoice recipient profile (from the contact): public_authority requires a Leitweg-ID (ER-08)
- customerNumberstring
  Customer number (assigned on finalisation)
  max. 40 characters
senderSenderSnapshot | nullrequired
Sender snapshot (taken on finalising)
- companyNamestringrequired
- ownerNamestring
- legalFormstring
- managingDirectorsstring
- streetstringrequired
- zipCodestringrequired
- citystringrequired
- countryCodestringrequired
- phonestring
- emailstring
- websitestring
- taxNumberstring
- vatIdstring
- smallBusinessbooleanrequired
- commercialRegisterobject
  - courtstring
  - numberstring
- bankobject
  - accountHolderstring
  - ibanstring
  - bicstring
  - bankNamestring
- invoiceFooterstring
issueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
serviceDatestring (date) | nullrequired
Date (YYYY-MM-DD)
servicePeriodServicePeriod | nullrequired
- fromstring (date)required
  Date (YYYY-MM-DD)
- tostring (date)required
  Date (YYYY-MM-DD)
serviceDateSource"entered" | "period" | "confirmed_issue_date" | "recurring" | "not_applicable" | nullrequired
Source of the date of supply (ST-13): confirmed_issue_date = confirmed by the user
issuanceInvoiceIssuance | nullrequired
Evidence of issue (from finalising, ST-14)
- finalizedAtstring (date-time)required
  Server time of finalising
- serverDatestring (date)required
  Calendar day of finalising (Europe/Berlin)
- issueDatestring (date)required
  Date (YYYY-MM-DD)
- issueDateSource"finalize_day" | "entered"required
  finalize_day = day of finalising, entered = entered in the draft
- deviationDaysintegerrequired
  Issue date minus finalising day in days (negative = earlier)
  -9007199254740991–9007199254740991
- reasonstring | nullrequired
  Reason for a differing issue date
- numberstring | nullrequired
- numberRangestringrequired
  Number range
dueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
paymentTermsDaysintegerrequired
-9007199254740991–9007199254740991
priceMode"net" | "gross"required
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
Tax treatment of the receipt
taxNoticestring | nullrequired
Mandatory notice (§ 19, § 13b, intra-Community supply …)
taxCaseInvoiceTaxCase | nullrequired
Tax case (tax assistant); saved at the latest when finalising
- factsobjectrequired
  - kind"goods" | "service" | "construction" | "property_service" | "electronic_service"required
    Type of supply
  - smallBusinessbooleanrequired
  - customerCountrystringrequired
    Country of residence of the recipient
    max. 2 characters
  - customerIsBusinessbooleanrequired
    Recipient is a business and receives the supply for its business
  - customerVatIdValidbooleanrequired
    a valid VAT ID of the recipient is available
  - destinationCountrystring | null
    Supply of goods: country of destination
    max. 2 characters
  - propertyCountrystring | null
    Service related to real estate: location of the property
    max. 2 characters
  - exemption"§ 4 Nr. 8 UStG" | "§ 4 Nr. 11 UStG" | "§ 4 Nr. 12 UStG" | "§ 4 Nr. 14 UStG" | "§ 4 Nr. 21 UStG" | "other" | null
    VAT exemption without input VAT deduction
- treatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
  Tax treatment of the receipt
- placeOfSupplystringrequired
  Place of supply (ISO country)
- legalBasisstringrequired
- noticeVariantenum | nullrequired
  Case variant of the mandatory notice (ST-03)
  Values: small_business, reverse_charge, reverse_charge_eu, intra_eu_supply, export, non_taxable, tax_exempt
- ustvaKzstring | nullrequired
  Advance VAT return form field of the tax base (not for standard taxation)
- reportingArray<"ustva" | "zm" | "none">required
- confidence"certain" | "likely" | "review"required
- assumedbooleanrequired
  Facts assumed from the invoice data (not entered)
- reasonsArray<string>required
- warningsArray<string>required
currency"EUR"required
subjectstringrequired
introTextstringrequired
closingTextstringrequired
referencestringrequired
linesArray<DocumentLine>required
- idstring
  stable line item ID (assigned by the server if empty)
  max. 40 characters
- type"item" | "text" | "subtotal"
  Line item, plain text line or subtotal
  Default: "item"
- articleIdstring
  Reference to the article master data
  max. 128 characters
- titlestringrequired
  max. 300 characters
- descriptionstring
  max. 5000 characters
- quantitynumber
  -1000000–1000000 · Default: 1
- unitstring
  Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
  max. 20 characters
- unitPriceCentsinteger
  Amount in cents
  -100000000000–100000000000 · Default: 0
- discountPercentnumber
  0–100
- taxRatenumber
  Tax rate in per cent (19, 7, 0 …)
  0–100 · Default: 19
- totalCentsinteger
  Amount in cents
  -100000000000–100000000000
- servicePeriodobject
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- projectIdstring
  max. 128 characters
- timeEntryIdsArray<string>
  max. 128 characters
totalsDocumentTotalsrequired
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - categorystringrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
deductionsArray<InvoiceDeduction>required
Final invoice: advance payments actually received and deducted (ST-09)
- invoiceIdstringrequired
  max. 128 characters
- numberstringrequired
- issueDatestring (date)required
  Date (YYYY-MM-DD)
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
- invoiceGrossCentsinteger
  Invoice amount of the progress invoice (ST-09)
  -100000000000–100000000000
- unpaidCentsinteger
  Unreceived remainder of the progress invoice – not deducted (ST-09)
  -100000000000–100000000000
amountDueCentsintegerrequired
Amount payable (gross less progress invoices)
-100000000000–100000000000
paidCentsintegerrequired
Amount in cents
-100000000000–100000000000
creditedCentsintegerrequired
reduced by invoice corrections (progress invoice: incl. the remainder settled with the final invoice)
-100000000000–100000000000
deductedCentsinteger | nullrequired
Progress invoice: amount received and deducted in the final invoice (ST-09)
-100000000000–100000000000
supersededCentsinteger | nullrequired
Progress invoice: unpaid remainder settled with the final invoice (ST-09)
-100000000000–100000000000
openCentsintegerrequired
Amount in cents
-100000000000–100000000000
relatedInvoiceIdstring | nullrequired
max. 128 characters
advanceInvoiceIdsArray<string>required
max. 128 characters
offerIdstring | nullrequired
max. 128 characters
projectIdstring | nullrequired
max. 128 characters
recurringInvoiceIdstring | nullrequired
max. 128 characters
canceledByInvoiceIdstring | nullrequired
Cancellation invoice for this invoice
max. 128 characters
debtIdstring | nullrequired
Debt in dunning (after handover)
max. 128 characters
showGiroCodebooleanrequired
einvoiceFormat"none" | "zugferd" | "xrechnung"required
language"de" | "en"required
Document language (fixed on finalisation)
dispatchobjectrequired
- countintegerrequired
  -9007199254740991–9007199254740991
- lastChannel"email" | "post" | nullrequired
- lastSentAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
pdfobject | nullrequired
archived PDF (after finalisation)
- sha256stringrequired
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
lockedbooleanrequired
lockedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
paidAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
handedOverAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/invoices/ID/duplicate' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 201

{
  "id": "string",
  "object": "invoice",
  "type": "invoice",
  "kind": "standard",
  "status": "draft",
  "number": "string",
  "contactId": "string",
  "recipient": {
    "name": "string",
    "addition": "string",
    "street": "",
    "zipCode": "",
    "city": "",
    "country": "DE",
    "email": "[email protected]",
    "vatId": "string",
    "leitwegId": "string",
    "einvoiceRecipientType": "business",
    "customerNumber": "string"
  },
  "sender": {
    "companyName": "string",
    "ownerName": "string",
    "legalForm": "string",
    "managingDirectors": "string",
    "street": "string",
    "zipCode": "string",
    "city": "string",
    "countryCode": "string",
    "phone": "string",
    "email": "string",
    "website": "string",
    "taxNumber": "string",
    "vatId": "string",
    "smallBusiness": false,
    "commercialRegister": {
      "court": "string",
      "number": "string"
    },
    "bank": {
      "accountHolder": "string",
      "iban": "string",
      "bic": "string",
      "bankName": "string"
    },
    "invoiceFooter": "string"
  },
  "issueDate": "2026-11-01",
  "serviceDate": "2026-11-01",
  "servicePeriod": {
    "from": "2026-11-01",
    "to": "2026-11-01"
  },
  "serviceDateSource": "entered",
  "issuance": {
    "finalizedAt": "2026-11-01T09:30:00.000Z",
    "serverDate": "2026-11-01",
    "issueDate": "2026-11-01",
    "issueDateSource": "finalize_day",
    "deviationDays": 0,
    "reason": "string",
    "number": "string",
    "numberRange": "string"
  },
  "dueDate": "2026-11-01",
  "paymentTermsDays": 0,
  "priceMode": "net",
  "taxTreatment": "regular",
  "taxNotice": "string",
  "taxCase": {
    "facts": {
      "kind": "goods",
      "smallBusiness": false,
      "customerCountry": "string",
      "customerIsBusiness": false,
      "customerVatIdValid": false,
      "destinationCountry": null,
      "propertyCountry": null,
      "exemption": null
    },
    "treatment": "regular",
    "placeOfSupply": "string",
    "legalBasis": "string",
    "noticeVariant": "small_business",
    "ustvaKz": "string",
    "reporting": [
      "ustva"
    ],
    "confidence": "certain",
    "assumed": false,
    "reasons": [
      "string"
    ],
    "warnings": [
      "string"
    ]
  },
  "currency": "EUR",
  "subject": "string",
  "introText": "string",
  "closingText": "string",
  "reference": "string",
  "lines": [
    {
      "id": "string",
      "type": "item",
      "articleId": "string",
      "title": "string",
      "description": "string",
      "quantity": 1,
      "unit": "string",
      "unitPriceCents": 0,
      "discountPercent": 0,
      "taxRate": 19,
      "totalCents": 0,
      "servicePeriod": {
        "from": "2026-11-01",
        "to": "2026-11-01"
      },
      "projectId": "string",
      "timeEntryIds": [
        "string"
      ]
    }
  ],
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0,
    "groups": [
      {
        "taxRate": 0,
        "category": "string",
        "netCents": 0,
        "taxCents": 0,
        "grossCents": 0
      }
    ]
  },
  "deductions": [
    {
      "invoiceId": "string",
      "number": "string",
      "issueDate": "2026-11-01",
      "netCents": 0,
      "taxCents": 0,
      "grossCents": 0,
      "groups": [
        {
          "taxRate": null,
          "netCents": null,
          "taxCents": null
        }
      ],
      "invoiceGrossCents": 0,
      "unpaidCents": 0
    }
  ],
  "amountDueCents": 0,
  "paidCents": 0,
  "creditedCents": 0,
  "deductedCents": 0,
  "supersededCents": 0,
  "openCents": 0,
  "relatedInvoiceId": "string",
  "advanceInvoiceIds": [
    "string"
  ],
  "offerId": "string",
  "projectId": "string",
  "recurringInvoiceId": "string",
  "canceledByInvoiceId": "string",
  "debtId": "string",
  "showGiroCode": false,
  "einvoiceFormat": "none",
  "language": "de",
  "dispatch": {
    "count": 0,
    "lastChannel": "email",
    "lastSentAt": "2026-11-01T09:30:00.000Z"
  },
  "pdf": {
    "sha256": "string",
    "createdAt": "2026-11-01T09:30:00.000Z"
  },
  "locked": false,
  "lockedAt": "2026-11-01T09:30:00.000Z",
  "paidAt": "2026-11-01T09:30:00.000Z",
  "handedOverAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

E-invoice of a finalised invoice

GET/api/v1/invoices/{id}/e-invoice

format=xrechnung returns XRechnung 3.0 (UBL, application/xml) – generated on first retrieval and archived unchanged. format=zugferd returns the archived invoice PDF with embedded factur-x.xml (PDF/A-3, profile EN 16931); only for invoices finalised with einvoiceFormat: "zugferd". If not specified: the invoice's format, otherwise XRechnung.

Permission: invoices:read

Path parameters

idstringrequired
Resource ID
max. 128 characters

Query parameters

format"xrechnung" | "zugferd"
xrechnung (XML) or zugferd (PDF)

Response 200

File (application/xml).

Possible errors: 400, 401, 403, 404, 409, 422, 429, 500

curl 'https://www.debt-flow.io/api/v1/invoices/ID/e-invoice' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Finalise invoice

POST/api/v1/invoices/{id}/finalize

Checks the mandatory details under § 14 German VAT Act (UStG), assigns the next number from the number range (without gaps), adopts the company master data as sender, sets the invoice, supply and due dates and locks the document (content hash, audit log). Missing details: 422 invoice_incomplete with details.problems.

Permission: invoices:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Headers

Idempotency-Keystring
Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
max. 255 characters

Body (JSON) · InvoiceFinalize

confirmServiceDateboolean
Without a date or period of supply: confirms that the supply was made on the invoice date (§ 14 (4) No. 6 UStG)
issueDateReasonstring
Reason if the invoice date differs from the day of finalising (will be logged)
max. 500 characters

Response 200 · Invoice

idstringrequired
max. 128 characters
object"invoice"required
type"invoice" | "credit_note" | "cancellation"required
kind"standard" | "advance" | "final"required
status"draft" | "open" | "partially_paid" | "paid" | "overdue" | "canceled"required
numberstring | nullrequired
Document number; assigned only on finalising
contactIdstring | nullrequired
max. 128 characters
recipientDocumentRecipientrequired
- namestringrequired
  Company or name
  max. 160 characters
- additionstring
  Address supplement, e.g. attn. Ms Muster
  max. 160 characters
- streetstringrequired
  max. 160 characters · Default: ""
- zipCodestringrequired
  max. 10 characters · Default: ""
- citystringrequired
  max. 80 characters · Default: ""
- countrystringrequired
  Country code ISO 3166-1 alpha-2
  max. 2 characters · Default: "DE"
- emailstring (email)
  Invoice recipient (email)
  max. 254 characters
- vatIdstring
  Recipient's VAT ID (required for reverse charge/intra-Community supply)
- leitwegIdstring
  Leitweg-ID (XRechnung to public authorities)
  max. 60 characters
- einvoiceRecipientType"business" | "public_authority"
  E-invoice recipient profile (from the contact): public_authority requires a Leitweg-ID (ER-08)
- customerNumberstring
  Customer number (assigned on finalisation)
  max. 40 characters
senderSenderSnapshot | nullrequired
Sender snapshot (taken on finalising)
- companyNamestringrequired
- ownerNamestring
- legalFormstring
- managingDirectorsstring
- streetstringrequired
- zipCodestringrequired
- citystringrequired
- countryCodestringrequired
- phonestring
- emailstring
- websitestring
- taxNumberstring
- vatIdstring
- smallBusinessbooleanrequired
- commercialRegisterobject
  - courtstring
  - numberstring
- bankobject
  - accountHolderstring
  - ibanstring
  - bicstring
  - bankNamestring
- invoiceFooterstring
issueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
serviceDatestring (date) | nullrequired
Date (YYYY-MM-DD)
servicePeriodServicePeriod | nullrequired
- fromstring (date)required
  Date (YYYY-MM-DD)
- tostring (date)required
  Date (YYYY-MM-DD)
serviceDateSource"entered" | "period" | "confirmed_issue_date" | "recurring" | "not_applicable" | nullrequired
Source of the date of supply (ST-13): confirmed_issue_date = confirmed by the user
issuanceInvoiceIssuance | nullrequired
Evidence of issue (from finalising, ST-14)
- finalizedAtstring (date-time)required
  Server time of finalising
- serverDatestring (date)required
  Calendar day of finalising (Europe/Berlin)
- issueDatestring (date)required
  Date (YYYY-MM-DD)
- issueDateSource"finalize_day" | "entered"required
  finalize_day = day of finalising, entered = entered in the draft
- deviationDaysintegerrequired
  Issue date minus finalising day in days (negative = earlier)
  -9007199254740991–9007199254740991
- reasonstring | nullrequired
  Reason for a differing issue date
- numberstring | nullrequired
- numberRangestringrequired
  Number range
dueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
paymentTermsDaysintegerrequired
-9007199254740991–9007199254740991
priceMode"net" | "gross"required
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
Tax treatment of the receipt
taxNoticestring | nullrequired
Mandatory notice (§ 19, § 13b, intra-Community supply …)
taxCaseInvoiceTaxCase | nullrequired
Tax case (tax assistant); saved at the latest when finalising
- factsobjectrequired
  - kind"goods" | "service" | "construction" | "property_service" | "electronic_service"required
    Type of supply
  - smallBusinessbooleanrequired
  - customerCountrystringrequired
    Country of residence of the recipient
    max. 2 characters
  - customerIsBusinessbooleanrequired
    Recipient is a business and receives the supply for its business
  - customerVatIdValidbooleanrequired
    a valid VAT ID of the recipient is available
  - destinationCountrystring | null
    Supply of goods: country of destination
    max. 2 characters
  - propertyCountrystring | null
    Service related to real estate: location of the property
    max. 2 characters
  - exemption"§ 4 Nr. 8 UStG" | "§ 4 Nr. 11 UStG" | "§ 4 Nr. 12 UStG" | "§ 4 Nr. 14 UStG" | "§ 4 Nr. 21 UStG" | "other" | null
    VAT exemption without input VAT deduction
- treatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
  Tax treatment of the receipt
- placeOfSupplystringrequired
  Place of supply (ISO country)
- legalBasisstringrequired
- noticeVariantenum | nullrequired
  Case variant of the mandatory notice (ST-03)
  Values: small_business, reverse_charge, reverse_charge_eu, intra_eu_supply, export, non_taxable, tax_exempt
- ustvaKzstring | nullrequired
  Advance VAT return form field of the tax base (not for standard taxation)
- reportingArray<"ustva" | "zm" | "none">required
- confidence"certain" | "likely" | "review"required
- assumedbooleanrequired
  Facts assumed from the invoice data (not entered)
- reasonsArray<string>required
- warningsArray<string>required
currency"EUR"required
subjectstringrequired
introTextstringrequired
closingTextstringrequired
referencestringrequired
linesArray<DocumentLine>required
- idstring
  stable line item ID (assigned by the server if empty)
  max. 40 characters
- type"item" | "text" | "subtotal"
  Line item, plain text line or subtotal
  Default: "item"
- articleIdstring
  Reference to the article master data
  max. 128 characters
- titlestringrequired
  max. 300 characters
- descriptionstring
  max. 5000 characters
- quantitynumber
  -1000000–1000000 · Default: 1
- unitstring
  Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
  max. 20 characters
- unitPriceCentsinteger
  Amount in cents
  -100000000000–100000000000 · Default: 0
- discountPercentnumber
  0–100
- taxRatenumber
  Tax rate in per cent (19, 7, 0 …)
  0–100 · Default: 19
- totalCentsinteger
  Amount in cents
  -100000000000–100000000000
- servicePeriodobject
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- projectIdstring
  max. 128 characters
- timeEntryIdsArray<string>
  max. 128 characters
totalsDocumentTotalsrequired
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - categorystringrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
deductionsArray<InvoiceDeduction>required
Final invoice: advance payments actually received and deducted (ST-09)
- invoiceIdstringrequired
  max. 128 characters
- numberstringrequired
- issueDatestring (date)required
  Date (YYYY-MM-DD)
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
- invoiceGrossCentsinteger
  Invoice amount of the progress invoice (ST-09)
  -100000000000–100000000000
- unpaidCentsinteger
  Unreceived remainder of the progress invoice – not deducted (ST-09)
  -100000000000–100000000000
amountDueCentsintegerrequired
Amount payable (gross less progress invoices)
-100000000000–100000000000
paidCentsintegerrequired
Amount in cents
-100000000000–100000000000
creditedCentsintegerrequired
reduced by invoice corrections (progress invoice: incl. the remainder settled with the final invoice)
-100000000000–100000000000
deductedCentsinteger | nullrequired
Progress invoice: amount received and deducted in the final invoice (ST-09)
-100000000000–100000000000
supersededCentsinteger | nullrequired
Progress invoice: unpaid remainder settled with the final invoice (ST-09)
-100000000000–100000000000
openCentsintegerrequired
Amount in cents
-100000000000–100000000000
relatedInvoiceIdstring | nullrequired
max. 128 characters
advanceInvoiceIdsArray<string>required
max. 128 characters
offerIdstring | nullrequired
max. 128 characters
projectIdstring | nullrequired
max. 128 characters
recurringInvoiceIdstring | nullrequired
max. 128 characters
canceledByInvoiceIdstring | nullrequired
Cancellation invoice for this invoice
max. 128 characters
debtIdstring | nullrequired
Debt in dunning (after handover)
max. 128 characters
showGiroCodebooleanrequired
einvoiceFormat"none" | "zugferd" | "xrechnung"required
language"de" | "en"required
Document language (fixed on finalisation)
dispatchobjectrequired
- countintegerrequired
  -9007199254740991–9007199254740991
- lastChannel"email" | "post" | nullrequired
- lastSentAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
pdfobject | nullrequired
archived PDF (after finalisation)
- sha256stringrequired
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
lockedbooleanrequired
lockedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
paidAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
handedOverAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/invoices/ID/finalize' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "confirmServiceDate": false,
  "issueDateReason": "string"
}'

Response 200

{
  "id": "string",
  "object": "invoice",
  "type": "invoice",
  "kind": "standard",
  "status": "draft",
  "number": "string",
  "contactId": "string",
  "recipient": {
    "name": "string",
    "addition": "string",
    "street": "",
    "zipCode": "",
    "city": "",
    "country": "DE",
    "email": "[email protected]",
    "vatId": "string",
    "leitwegId": "string",
    "einvoiceRecipientType": "business",
    "customerNumber": "string"
  },
  "sender": {
    "companyName": "string",
    "ownerName": "string",
    "legalForm": "string",
    "managingDirectors": "string",
    "street": "string",
    "zipCode": "string",
    "city": "string",
    "countryCode": "string",
    "phone": "string",
    "email": "string",
    "website": "string",
    "taxNumber": "string",
    "vatId": "string",
    "smallBusiness": false,
    "commercialRegister": {
      "court": "string",
      "number": "string"
    },
    "bank": {
      "accountHolder": "string",
      "iban": "string",
      "bic": "string",
      "bankName": "string"
    },
    "invoiceFooter": "string"
  },
  "issueDate": "2026-11-01",
  "serviceDate": "2026-11-01",
  "servicePeriod": {
    "from": "2026-11-01",
    "to": "2026-11-01"
  },
  "serviceDateSource": "entered",
  "issuance": {
    "finalizedAt": "2026-11-01T09:30:00.000Z",
    "serverDate": "2026-11-01",
    "issueDate": "2026-11-01",
    "issueDateSource": "finalize_day",
    "deviationDays": 0,
    "reason": "string",
    "number": "string",
    "numberRange": "string"
  },
  "dueDate": "2026-11-01",
  "paymentTermsDays": 0,
  "priceMode": "net",
  "taxTreatment": "regular",
  "taxNotice": "string",
  "taxCase": {
    "facts": {
      "kind": "goods",
      "smallBusiness": false,
      "customerCountry": "string",
      "customerIsBusiness": false,
      "customerVatIdValid": false,
      "destinationCountry": null,
      "propertyCountry": null,
      "exemption": null
    },
    "treatment": "regular",
    "placeOfSupply": "string",
    "legalBasis": "string",
    "noticeVariant": "small_business",
    "ustvaKz": "string",
    "reporting": [
      "ustva"
    ],
    "confidence": "certain",
    "assumed": false,
    "reasons": [
      "string"
    ],
    "warnings": [
      "string"
    ]
  },
  "currency": "EUR",
  "subject": "string",
  "introText": "string",
  "closingText": "string",
  "reference": "string",
  "lines": [
    {
      "id": "string",
      "type": "item",
      "articleId": "string",
      "title": "string",
      "description": "string",
      "quantity": 1,
      "unit": "string",
      "unitPriceCents": 0,
      "discountPercent": 0,
      "taxRate": 19,
      "totalCents": 0,
      "servicePeriod": {
        "from": "2026-11-01",
        "to": "2026-11-01"
      },
      "projectId": "string",
      "timeEntryIds": [
        "string"
      ]
    }
  ],
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0,
    "groups": [
      {
        "taxRate": 0,
        "category": "string",
        "netCents": 0,
        "taxCents": 0,
        "grossCents": 0
      }
    ]
  },
  "deductions": [
    {
      "invoiceId": "string",
      "number": "string",
      "issueDate": "2026-11-01",
      "netCents": 0,
      "taxCents": 0,
      "grossCents": 0,
      "groups": [
        {
          "taxRate": null,
          "netCents": null,
          "taxCents": null
        }
      ],
      "invoiceGrossCents": 0,
      "unpaidCents": 0
    }
  ],
  "amountDueCents": 0,
  "paidCents": 0,
  "creditedCents": 0,
  "deductedCents": 0,
  "supersededCents": 0,
  "openCents": 0,
  "relatedInvoiceId": "string",
  "advanceInvoiceIds": [
    "string"
  ],
  "offerId": "string",
  "projectId": "string",
  "recurringInvoiceId": "string",
  "canceledByInvoiceId": "string",
  "debtId": "string",
  "showGiroCode": false,
  "einvoiceFormat": "none",
  "language": "de",
  "dispatch": {
    "count": 0,
    "lastChannel": "email",
    "lastSentAt": "2026-11-01T09:30:00.000Z"
  },
  "pdf": {
    "sha256": "string",
    "createdAt": "2026-11-01T09:30:00.000Z"
  },
  "locked": false,
  "lockedAt": "2026-11-01T09:30:00.000Z",
  "paidAt": "2026-11-01T09:30:00.000Z",
  "handedOverAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Hand invoice over to dunning

POST/api/v1/invoices/{id}/hand-over

Creates a debt (/debts) for the outstanding amount with a reference to the invoice; from then on the dunning run applies. Prerequisites: finalised, outstanding amount, contact assigned. Automatic via setting (collection.enabled).

Permission: invoices:write, debts:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Headers

Idempotency-Keystring
Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
max. 255 characters

Response 200 · Invoice

idstringrequired
max. 128 characters
object"invoice"required
type"invoice" | "credit_note" | "cancellation"required
kind"standard" | "advance" | "final"required
status"draft" | "open" | "partially_paid" | "paid" | "overdue" | "canceled"required
numberstring | nullrequired
Document number; assigned only on finalising
contactIdstring | nullrequired
max. 128 characters
recipientDocumentRecipientrequired
- namestringrequired
  Company or name
  max. 160 characters
- additionstring
  Address supplement, e.g. attn. Ms Muster
  max. 160 characters
- streetstringrequired
  max. 160 characters · Default: ""
- zipCodestringrequired
  max. 10 characters · Default: ""
- citystringrequired
  max. 80 characters · Default: ""
- countrystringrequired
  Country code ISO 3166-1 alpha-2
  max. 2 characters · Default: "DE"
- emailstring (email)
  Invoice recipient (email)
  max. 254 characters
- vatIdstring
  Recipient's VAT ID (required for reverse charge/intra-Community supply)
- leitwegIdstring
  Leitweg-ID (XRechnung to public authorities)
  max. 60 characters
- einvoiceRecipientType"business" | "public_authority"
  E-invoice recipient profile (from the contact): public_authority requires a Leitweg-ID (ER-08)
- customerNumberstring
  Customer number (assigned on finalisation)
  max. 40 characters
senderSenderSnapshot | nullrequired
Sender snapshot (taken on finalising)
- companyNamestringrequired
- ownerNamestring
- legalFormstring
- managingDirectorsstring
- streetstringrequired
- zipCodestringrequired
- citystringrequired
- countryCodestringrequired
- phonestring
- emailstring
- websitestring
- taxNumberstring
- vatIdstring
- smallBusinessbooleanrequired
- commercialRegisterobject
  - courtstring
  - numberstring
- bankobject
  - accountHolderstring
  - ibanstring
  - bicstring
  - bankNamestring
- invoiceFooterstring
issueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
serviceDatestring (date) | nullrequired
Date (YYYY-MM-DD)
servicePeriodServicePeriod | nullrequired
- fromstring (date)required
  Date (YYYY-MM-DD)
- tostring (date)required
  Date (YYYY-MM-DD)
serviceDateSource"entered" | "period" | "confirmed_issue_date" | "recurring" | "not_applicable" | nullrequired
Source of the date of supply (ST-13): confirmed_issue_date = confirmed by the user
issuanceInvoiceIssuance | nullrequired
Evidence of issue (from finalising, ST-14)
- finalizedAtstring (date-time)required
  Server time of finalising
- serverDatestring (date)required
  Calendar day of finalising (Europe/Berlin)
- issueDatestring (date)required
  Date (YYYY-MM-DD)
- issueDateSource"finalize_day" | "entered"required
  finalize_day = day of finalising, entered = entered in the draft
- deviationDaysintegerrequired
  Issue date minus finalising day in days (negative = earlier)
  -9007199254740991–9007199254740991
- reasonstring | nullrequired
  Reason for a differing issue date
- numberstring | nullrequired
- numberRangestringrequired
  Number range
dueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
paymentTermsDaysintegerrequired
-9007199254740991–9007199254740991
priceMode"net" | "gross"required
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
Tax treatment of the receipt
taxNoticestring | nullrequired
Mandatory notice (§ 19, § 13b, intra-Community supply …)
taxCaseInvoiceTaxCase | nullrequired
Tax case (tax assistant); saved at the latest when finalising
- factsobjectrequired
  - kind"goods" | "service" | "construction" | "property_service" | "electronic_service"required
    Type of supply
  - smallBusinessbooleanrequired
  - customerCountrystringrequired
    Country of residence of the recipient
    max. 2 characters
  - customerIsBusinessbooleanrequired
    Recipient is a business and receives the supply for its business
  - customerVatIdValidbooleanrequired
    a valid VAT ID of the recipient is available
  - destinationCountrystring | null
    Supply of goods: country of destination
    max. 2 characters
  - propertyCountrystring | null
    Service related to real estate: location of the property
    max. 2 characters
  - exemption"§ 4 Nr. 8 UStG" | "§ 4 Nr. 11 UStG" | "§ 4 Nr. 12 UStG" | "§ 4 Nr. 14 UStG" | "§ 4 Nr. 21 UStG" | "other" | null
    VAT exemption without input VAT deduction
- treatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
  Tax treatment of the receipt
- placeOfSupplystringrequired
  Place of supply (ISO country)
- legalBasisstringrequired
- noticeVariantenum | nullrequired
  Case variant of the mandatory notice (ST-03)
  Values: small_business, reverse_charge, reverse_charge_eu, intra_eu_supply, export, non_taxable, tax_exempt
- ustvaKzstring | nullrequired
  Advance VAT return form field of the tax base (not for standard taxation)
- reportingArray<"ustva" | "zm" | "none">required
- confidence"certain" | "likely" | "review"required
- assumedbooleanrequired
  Facts assumed from the invoice data (not entered)
- reasonsArray<string>required
- warningsArray<string>required
currency"EUR"required
subjectstringrequired
introTextstringrequired
closingTextstringrequired
referencestringrequired
linesArray<DocumentLine>required
- idstring
  stable line item ID (assigned by the server if empty)
  max. 40 characters
- type"item" | "text" | "subtotal"
  Line item, plain text line or subtotal
  Default: "item"
- articleIdstring
  Reference to the article master data
  max. 128 characters
- titlestringrequired
  max. 300 characters
- descriptionstring
  max. 5000 characters
- quantitynumber
  -1000000–1000000 · Default: 1
- unitstring
  Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
  max. 20 characters
- unitPriceCentsinteger
  Amount in cents
  -100000000000–100000000000 · Default: 0
- discountPercentnumber
  0–100
- taxRatenumber
  Tax rate in per cent (19, 7, 0 …)
  0–100 · Default: 19
- totalCentsinteger
  Amount in cents
  -100000000000–100000000000
- servicePeriodobject
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- projectIdstring
  max. 128 characters
- timeEntryIdsArray<string>
  max. 128 characters
totalsDocumentTotalsrequired
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - categorystringrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
deductionsArray<InvoiceDeduction>required
Final invoice: advance payments actually received and deducted (ST-09)
- invoiceIdstringrequired
  max. 128 characters
- numberstringrequired
- issueDatestring (date)required
  Date (YYYY-MM-DD)
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
- invoiceGrossCentsinteger
  Invoice amount of the progress invoice (ST-09)
  -100000000000–100000000000
- unpaidCentsinteger
  Unreceived remainder of the progress invoice – not deducted (ST-09)
  -100000000000–100000000000
amountDueCentsintegerrequired
Amount payable (gross less progress invoices)
-100000000000–100000000000
paidCentsintegerrequired
Amount in cents
-100000000000–100000000000
creditedCentsintegerrequired
reduced by invoice corrections (progress invoice: incl. the remainder settled with the final invoice)
-100000000000–100000000000
deductedCentsinteger | nullrequired
Progress invoice: amount received and deducted in the final invoice (ST-09)
-100000000000–100000000000
supersededCentsinteger | nullrequired
Progress invoice: unpaid remainder settled with the final invoice (ST-09)
-100000000000–100000000000
openCentsintegerrequired
Amount in cents
-100000000000–100000000000
relatedInvoiceIdstring | nullrequired
max. 128 characters
advanceInvoiceIdsArray<string>required
max. 128 characters
offerIdstring | nullrequired
max. 128 characters
projectIdstring | nullrequired
max. 128 characters
recurringInvoiceIdstring | nullrequired
max. 128 characters
canceledByInvoiceIdstring | nullrequired
Cancellation invoice for this invoice
max. 128 characters
debtIdstring | nullrequired
Debt in dunning (after handover)
max. 128 characters
showGiroCodebooleanrequired
einvoiceFormat"none" | "zugferd" | "xrechnung"required
language"de" | "en"required
Document language (fixed on finalisation)
dispatchobjectrequired
- countintegerrequired
  -9007199254740991–9007199254740991
- lastChannel"email" | "post" | nullrequired
- lastSentAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
pdfobject | nullrequired
archived PDF (after finalisation)
- sha256stringrequired
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
lockedbooleanrequired
lockedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
paidAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
handedOverAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/invoices/ID/hand-over' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "id": "string",
  "object": "invoice",
  "type": "invoice",
  "kind": "standard",
  "status": "draft",
  "number": "string",
  "contactId": "string",
  "recipient": {
    "name": "string",
    "addition": "string",
    "street": "",
    "zipCode": "",
    "city": "",
    "country": "DE",
    "email": "[email protected]",
    "vatId": "string",
    "leitwegId": "string",
    "einvoiceRecipientType": "business",
    "customerNumber": "string"
  },
  "sender": {
    "companyName": "string",
    "ownerName": "string",
    "legalForm": "string",
    "managingDirectors": "string",
    "street": "string",
    "zipCode": "string",
    "city": "string",
    "countryCode": "string",
    "phone": "string",
    "email": "string",
    "website": "string",
    "taxNumber": "string",
    "vatId": "string",
    "smallBusiness": false,
    "commercialRegister": {
      "court": "string",
      "number": "string"
    },
    "bank": {
      "accountHolder": "string",
      "iban": "string",
      "bic": "string",
      "bankName": "string"
    },
    "invoiceFooter": "string"
  },
  "issueDate": "2026-11-01",
  "serviceDate": "2026-11-01",
  "servicePeriod": {
    "from": "2026-11-01",
    "to": "2026-11-01"
  },
  "serviceDateSource": "entered",
  "issuance": {
    "finalizedAt": "2026-11-01T09:30:00.000Z",
    "serverDate": "2026-11-01",
    "issueDate": "2026-11-01",
    "issueDateSource": "finalize_day",
    "deviationDays": 0,
    "reason": "string",
    "number": "string",
    "numberRange": "string"
  },
  "dueDate": "2026-11-01",
  "paymentTermsDays": 0,
  "priceMode": "net",
  "taxTreatment": "regular",
  "taxNotice": "string",
  "taxCase": {
    "facts": {
      "kind": "goods",
      "smallBusiness": false,
      "customerCountry": "string",
      "customerIsBusiness": false,
      "customerVatIdValid": false,
      "destinationCountry": null,
      "propertyCountry": null,
      "exemption": null
    },
    "treatment": "regular",
    "placeOfSupply": "string",
    "legalBasis": "string",
    "noticeVariant": "small_business",
    "ustvaKz": "string",
    "reporting": [
      "ustva"
    ],
    "confidence": "certain",
    "assumed": false,
    "reasons": [
      "string"
    ],
    "warnings": [
      "string"
    ]
  },
  "currency": "EUR",
  "subject": "string",
  "introText": "string",
  "closingText": "string",
  "reference": "string",
  "lines": [
    {
      "id": "string",
      "type": "item",
      "articleId": "string",
      "title": "string",
      "description": "string",
      "quantity": 1,
      "unit": "string",
      "unitPriceCents": 0,
      "discountPercent": 0,
      "taxRate": 19,
      "totalCents": 0,
      "servicePeriod": {
        "from": "2026-11-01",
        "to": "2026-11-01"
      },
      "projectId": "string",
      "timeEntryIds": [
        "string"
      ]
    }
  ],
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0,
    "groups": [
      {
        "taxRate": 0,
        "category": "string",
        "netCents": 0,
        "taxCents": 0,
        "grossCents": 0
      }
    ]
  },
  "deductions": [
    {
      "invoiceId": "string",
      "number": "string",
      "issueDate": "2026-11-01",
      "netCents": 0,
      "taxCents": 0,
      "grossCents": 0,
      "groups": [
        {
          "taxRate": null,
          "netCents": null,
          "taxCents": null
        }
      ],
      "invoiceGrossCents": 0,
      "unpaidCents": 0
    }
  ],
  "amountDueCents": 0,
  "paidCents": 0,
  "creditedCents": 0,
  "deductedCents": 0,
  "supersededCents": 0,
  "openCents": 0,
  "relatedInvoiceId": "string",
  "advanceInvoiceIds": [
    "string"
  ],
  "offerId": "string",
  "projectId": "string",
  "recurringInvoiceId": "string",
  "canceledByInvoiceId": "string",
  "debtId": "string",
  "showGiroCode": false,
  "einvoiceFormat": "none",
  "language": "de",
  "dispatch": {
    "count": 0,
    "lastChannel": "email",
    "lastSentAt": "2026-11-01T09:30:00.000Z"
  },
  "pdf": {
    "sha256": "string",
    "createdAt": "2026-11-01T09:30:00.000Z"
  },
  "locked": false,
  "lockedAt": "2026-11-01T09:30:00.000Z",
  "paidAt": "2026-11-01T09:30:00.000Z",
  "handedOverAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Store the original PDF of an imported legacy invoice

POST/api/v1/invoices/{id}/original-pdf

Only for imported, finalised legacy invoices (lexoffice, sevDesk, Papierkram, CSV). The PDF is archived unchanged (GoBD, hash chain) and then delivered under /invoices/{id}/pdf. An original that is already stored is not replaced (409 original_pdf_exists).

Permission: invoices:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Body (multipart/form-data)

filestring (binary)required
application/pdf, application/octet-stream, , max. 20480 KB

Response 200 · Invoice

idstringrequired
max. 128 characters
object"invoice"required
type"invoice" | "credit_note" | "cancellation"required
kind"standard" | "advance" | "final"required
status"draft" | "open" | "partially_paid" | "paid" | "overdue" | "canceled"required
numberstring | nullrequired
Document number; assigned only on finalising
contactIdstring | nullrequired
max. 128 characters
recipientDocumentRecipientrequired
- namestringrequired
  Company or name
  max. 160 characters
- additionstring
  Address supplement, e.g. attn. Ms Muster
  max. 160 characters
- streetstringrequired
  max. 160 characters · Default: ""
- zipCodestringrequired
  max. 10 characters · Default: ""
- citystringrequired
  max. 80 characters · Default: ""
- countrystringrequired
  Country code ISO 3166-1 alpha-2
  max. 2 characters · Default: "DE"
- emailstring (email)
  Invoice recipient (email)
  max. 254 characters
- vatIdstring
  Recipient's VAT ID (required for reverse charge/intra-Community supply)
- leitwegIdstring
  Leitweg-ID (XRechnung to public authorities)
  max. 60 characters
- einvoiceRecipientType"business" | "public_authority"
  E-invoice recipient profile (from the contact): public_authority requires a Leitweg-ID (ER-08)
- customerNumberstring
  Customer number (assigned on finalisation)
  max. 40 characters
senderSenderSnapshot | nullrequired
Sender snapshot (taken on finalising)
- companyNamestringrequired
- ownerNamestring
- legalFormstring
- managingDirectorsstring
- streetstringrequired
- zipCodestringrequired
- citystringrequired
- countryCodestringrequired
- phonestring
- emailstring
- websitestring
- taxNumberstring
- vatIdstring
- smallBusinessbooleanrequired
- commercialRegisterobject
  - courtstring
  - numberstring
- bankobject
  - accountHolderstring
  - ibanstring
  - bicstring
  - bankNamestring
- invoiceFooterstring
issueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
serviceDatestring (date) | nullrequired
Date (YYYY-MM-DD)
servicePeriodServicePeriod | nullrequired
- fromstring (date)required
  Date (YYYY-MM-DD)
- tostring (date)required
  Date (YYYY-MM-DD)
serviceDateSource"entered" | "period" | "confirmed_issue_date" | "recurring" | "not_applicable" | nullrequired
Source of the date of supply (ST-13): confirmed_issue_date = confirmed by the user
issuanceInvoiceIssuance | nullrequired
Evidence of issue (from finalising, ST-14)
- finalizedAtstring (date-time)required
  Server time of finalising
- serverDatestring (date)required
  Calendar day of finalising (Europe/Berlin)
- issueDatestring (date)required
  Date (YYYY-MM-DD)
- issueDateSource"finalize_day" | "entered"required
  finalize_day = day of finalising, entered = entered in the draft
- deviationDaysintegerrequired
  Issue date minus finalising day in days (negative = earlier)
  -9007199254740991–9007199254740991
- reasonstring | nullrequired
  Reason for a differing issue date
- numberstring | nullrequired
- numberRangestringrequired
  Number range
dueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
paymentTermsDaysintegerrequired
-9007199254740991–9007199254740991
priceMode"net" | "gross"required
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
Tax treatment of the receipt
taxNoticestring | nullrequired
Mandatory notice (§ 19, § 13b, intra-Community supply …)
taxCaseInvoiceTaxCase | nullrequired
Tax case (tax assistant); saved at the latest when finalising
- factsobjectrequired
  - kind"goods" | "service" | "construction" | "property_service" | "electronic_service"required
    Type of supply
  - smallBusinessbooleanrequired
  - customerCountrystringrequired
    Country of residence of the recipient
    max. 2 characters
  - customerIsBusinessbooleanrequired
    Recipient is a business and receives the supply for its business
  - customerVatIdValidbooleanrequired
    a valid VAT ID of the recipient is available
  - destinationCountrystring | null
    Supply of goods: country of destination
    max. 2 characters
  - propertyCountrystring | null
    Service related to real estate: location of the property
    max. 2 characters
  - exemption"§ 4 Nr. 8 UStG" | "§ 4 Nr. 11 UStG" | "§ 4 Nr. 12 UStG" | "§ 4 Nr. 14 UStG" | "§ 4 Nr. 21 UStG" | "other" | null
    VAT exemption without input VAT deduction
- treatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
  Tax treatment of the receipt
- placeOfSupplystringrequired
  Place of supply (ISO country)
- legalBasisstringrequired
- noticeVariantenum | nullrequired
  Case variant of the mandatory notice (ST-03)
  Values: small_business, reverse_charge, reverse_charge_eu, intra_eu_supply, export, non_taxable, tax_exempt
- ustvaKzstring | nullrequired
  Advance VAT return form field of the tax base (not for standard taxation)
- reportingArray<"ustva" | "zm" | "none">required
- confidence"certain" | "likely" | "review"required
- assumedbooleanrequired
  Facts assumed from the invoice data (not entered)
- reasonsArray<string>required
- warningsArray<string>required
currency"EUR"required
subjectstringrequired
introTextstringrequired
closingTextstringrequired
referencestringrequired
linesArray<DocumentLine>required
- idstring
  stable line item ID (assigned by the server if empty)
  max. 40 characters
- type"item" | "text" | "subtotal"
  Line item, plain text line or subtotal
  Default: "item"
- articleIdstring
  Reference to the article master data
  max. 128 characters
- titlestringrequired
  max. 300 characters
- descriptionstring
  max. 5000 characters
- quantitynumber
  -1000000–1000000 · Default: 1
- unitstring
  Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
  max. 20 characters
- unitPriceCentsinteger
  Amount in cents
  -100000000000–100000000000 · Default: 0
- discountPercentnumber
  0–100
- taxRatenumber
  Tax rate in per cent (19, 7, 0 …)
  0–100 · Default: 19
- totalCentsinteger
  Amount in cents
  -100000000000–100000000000
- servicePeriodobject
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- projectIdstring
  max. 128 characters
- timeEntryIdsArray<string>
  max. 128 characters
totalsDocumentTotalsrequired
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - categorystringrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
deductionsArray<InvoiceDeduction>required
Final invoice: advance payments actually received and deducted (ST-09)
- invoiceIdstringrequired
  max. 128 characters
- numberstringrequired
- issueDatestring (date)required
  Date (YYYY-MM-DD)
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
- invoiceGrossCentsinteger
  Invoice amount of the progress invoice (ST-09)
  -100000000000–100000000000
- unpaidCentsinteger
  Unreceived remainder of the progress invoice – not deducted (ST-09)
  -100000000000–100000000000
amountDueCentsintegerrequired
Amount payable (gross less progress invoices)
-100000000000–100000000000
paidCentsintegerrequired
Amount in cents
-100000000000–100000000000
creditedCentsintegerrequired
reduced by invoice corrections (progress invoice: incl. the remainder settled with the final invoice)
-100000000000–100000000000
deductedCentsinteger | nullrequired
Progress invoice: amount received and deducted in the final invoice (ST-09)
-100000000000–100000000000
supersededCentsinteger | nullrequired
Progress invoice: unpaid remainder settled with the final invoice (ST-09)
-100000000000–100000000000
openCentsintegerrequired
Amount in cents
-100000000000–100000000000
relatedInvoiceIdstring | nullrequired
max. 128 characters
advanceInvoiceIdsArray<string>required
max. 128 characters
offerIdstring | nullrequired
max. 128 characters
projectIdstring | nullrequired
max. 128 characters
recurringInvoiceIdstring | nullrequired
max. 128 characters
canceledByInvoiceIdstring | nullrequired
Cancellation invoice for this invoice
max. 128 characters
debtIdstring | nullrequired
Debt in dunning (after handover)
max. 128 characters
showGiroCodebooleanrequired
einvoiceFormat"none" | "zugferd" | "xrechnung"required
language"de" | "en"required
Document language (fixed on finalisation)
dispatchobjectrequired
- countintegerrequired
  -9007199254740991–9007199254740991
- lastChannel"email" | "post" | nullrequired
- lastSentAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
pdfobject | nullrequired
archived PDF (after finalisation)
- sha256stringrequired
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
lockedbooleanrequired
lockedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
paidAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
handedOverAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 413, 415, 429, 500

curl

curl -X POST 'https://www.debt-flow.io/api/v1/invoices/ID/original-pdf' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -F 'file=@file'

Response 200

{
  "id": "string",
  "object": "invoice",
  "type": "invoice",
  "kind": "standard",
  "status": "draft",
  "number": "string",
  "contactId": "string",
  "recipient": {
    "name": "string",
    "addition": "string",
    "street": "",
    "zipCode": "",
    "city": "",
    "country": "DE",
    "email": "[email protected]",
    "vatId": "string",
    "leitwegId": "string",
    "einvoiceRecipientType": "business",
    "customerNumber": "string"
  },
  "sender": {
    "companyName": "string",
    "ownerName": "string",
    "legalForm": "string",
    "managingDirectors": "string",
    "street": "string",
    "zipCode": "string",
    "city": "string",
    "countryCode": "string",
    "phone": "string",
    "email": "string",
    "website": "string",
    "taxNumber": "string",
    "vatId": "string",
    "smallBusiness": false,
    "commercialRegister": {
      "court": "string",
      "number": "string"
    },
    "bank": {
      "accountHolder": "string",
      "iban": "string",
      "bic": "string",
      "bankName": "string"
    },
    "invoiceFooter": "string"
  },
  "issueDate": "2026-11-01",
  "serviceDate": "2026-11-01",
  "servicePeriod": {
    "from": "2026-11-01",
    "to": "2026-11-01"
  },
  "serviceDateSource": "entered",
  "issuance": {
    "finalizedAt": "2026-11-01T09:30:00.000Z",
    "serverDate": "2026-11-01",
    "issueDate": "2026-11-01",
    "issueDateSource": "finalize_day",
    "deviationDays": 0,
    "reason": "string",
    "number": "string",
    "numberRange": "string"
  },
  "dueDate": "2026-11-01",
  "paymentTermsDays": 0,
  "priceMode": "net",
  "taxTreatment": "regular",
  "taxNotice": "string",
  "taxCase": {
    "facts": {
      "kind": "goods",
      "smallBusiness": false,
      "customerCountry": "string",
      "customerIsBusiness": false,
      "customerVatIdValid": false,
      "destinationCountry": null,
      "propertyCountry": null,
      "exemption": null
    },
    "treatment": "regular",
    "placeOfSupply": "string",
    "legalBasis": "string",
    "noticeVariant": "small_business",
    "ustvaKz": "string",
    "reporting": [
      "ustva"
    ],
    "confidence": "certain",
    "assumed": false,
    "reasons": [
      "string"
    ],
    "warnings": [
      "string"
    ]
  },
  "currency": "EUR",
  "subject": "string",
  "introText": "string",
  "closingText": "string",
  "reference": "string",
  "lines": [
    {
      "id": "string",
      "type": "item",
      "articleId": "string",
      "title": "string",
      "description": "string",
      "quantity": 1,
      "unit": "string",
      "unitPriceCents": 0,
      "discountPercent": 0,
      "taxRate": 19,
      "totalCents": 0,
      "servicePeriod": {
        "from": "2026-11-01",
        "to": "2026-11-01"
      },
      "projectId": "string",
      "timeEntryIds": [
        "string"
      ]
    }
  ],
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0,
    "groups": [
      {
        "taxRate": 0,
        "category": "string",
        "netCents": 0,
        "taxCents": 0,
        "grossCents": 0
      }
    ]
  },
  "deductions": [
    {
      "invoiceId": "string",
      "number": "string",
      "issueDate": "2026-11-01",
      "netCents": 0,
      "taxCents": 0,
      "grossCents": 0,
      "groups": [
        {
          "taxRate": null,
          "netCents": null,
          "taxCents": null
        }
      ],
      "invoiceGrossCents": 0,
      "unpaidCents": 0
    }
  ],
  "amountDueCents": 0,
  "paidCents": 0,
  "creditedCents": 0,
  "deductedCents": 0,
  "supersededCents": 0,
  "openCents": 0,
  "relatedInvoiceId": "string",
  "advanceInvoiceIds": [
    "string"
  ],
  "offerId": "string",
  "projectId": "string",
  "recurringInvoiceId": "string",
  "canceledByInvoiceId": "string",
  "debtId": "string",
  "showGiroCode": false,
  "einvoiceFormat": "none",
  "language": "de",
  "dispatch": {
    "count": 0,
    "lastChannel": "email",
    "lastSentAt": "2026-11-01T09:30:00.000Z"
  },
  "pdf": {
    "sha256": "string",
    "createdAt": "2026-11-01T09:30:00.000Z"
  },
  "locked": false,
  "lockedAt": "2026-11-01T09:30:00.000Z",
  "paidAt": "2026-11-01T09:30:00.000Z",
  "handedOverAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Payments of an invoice

GET/api/v1/invoices/{id}/payments

For credit notes and cancellation invoices: refunds to the customer.

Permission: invoices:read

Path parameters

idstringrequired
Resource ID
max. 128 characters

Query parameters

limitinteger
Number of entries (1–100)
1–100 · Default: 25
cursorstring
`nextCursor` of the previous page
max. 500 characters

Response 200

object"list"required
dataArray<InvoicePayment>required
- idstringrequired
  max. 128 characters
- invoiceIdstringrequired
  max. 128 characters
- amountCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- datestring (date)required
  Date (YYYY-MM-DD)
- method"bank" | "cash" | "stripe" | "paypal" | "offset" | "other"required
- bankTransactionIdstring | nullrequired
  max. 128 characters
- notestring | nullrequired
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
hasMorebooleanrequired
nextCursorstring | nullrequired

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/invoices/ID/payments' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "invoiceId": "string",
      "amountCents": 0,
      "date": "2026-11-01",
      "method": "bank",
      "bankTransactionId": "string",
      "note": "string",
      "createdAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Record payment

POST/api/v1/invoices/{id}/payments

Records an incoming payment and recalculates the outstanding amount and status (partially paid/paid). Amounts exceeding the outstanding amount: 422 overpayment. Triggers invoice.partially_paid or invoice.paid respectively.

Permission: invoices:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Headers

Idempotency-Keystring
Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
max. 255 characters

Body (JSON) · InvoicePaymentCreate

amountCentsintegerrequired
Amount in cents
0–100000000000
datestring (date)required
Date (YYYY-MM-DD)
method"bank" | "cash" | "stripe" | "paypal" | "offset" | "other"
Default: "bank"
bankTransactionIdstring
max. 128 characters
notestring
max. 500 characters

Response 201 · InvoicePaymentResult

paymentInvoicePaymentrequired
- idstringrequired
  max. 128 characters
- invoiceIdstringrequired
  max. 128 characters
- amountCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- datestring (date)required
  Date (YYYY-MM-DD)
- method"bank" | "cash" | "stripe" | "paypal" | "offset" | "other"required
- bankTransactionIdstring | nullrequired
  max. 128 characters
- notestring | nullrequired
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
invoiceInvoicerequired
- idstringrequired
  max. 128 characters
- object"invoice"required
- type"invoice" | "credit_note" | "cancellation"required
- kind"standard" | "advance" | "final"required
- status"draft" | "open" | "partially_paid" | "paid" | "overdue" | "canceled"required
- numberstring | nullrequired
  Document number; assigned only on finalising
- contactIdstring | nullrequired
  max. 128 characters
- recipientDocumentRecipientrequired
  - namestringrequired
    Company or name
    max. 160 characters
  - additionstring
    Address supplement, e.g. attn. Ms Muster
    max. 160 characters
  - streetstringrequired
    max. 160 characters · Default: ""
  - zipCodestringrequired
    max. 10 characters · Default: ""
  - citystringrequired
    max. 80 characters · Default: ""
  - countrystringrequired
    Country code ISO 3166-1 alpha-2
    max. 2 characters · Default: "DE"
  - emailstring (email)
    Invoice recipient (email)
    max. 254 characters
  - vatIdstring
    Recipient's VAT ID (required for reverse charge/intra-Community supply)
  - leitwegIdstring
    Leitweg-ID (XRechnung to public authorities)
    max. 60 characters
  - einvoiceRecipientType"business" | "public_authority"
    E-invoice recipient profile (from the contact): public_authority requires a Leitweg-ID (ER-08)
  - customerNumberstring
    Customer number (assigned on finalisation)
    max. 40 characters
- senderSenderSnapshot | nullrequired
  Sender snapshot (taken on finalising)
  - companyNamestringrequired
  - ownerNamestring
  - legalFormstring
  - managingDirectorsstring
  - streetstringrequired
  - zipCodestringrequired
  - citystringrequired
  - countryCodestringrequired
  - phonestring
  - emailstring
  - websitestring
  - taxNumberstring
  - vatIdstring
  - smallBusinessbooleanrequired
  - commercialRegisterobject
  - bankobject
  - invoiceFooterstring
- issueDatestring (date) | nullrequired
  Date (YYYY-MM-DD)
- serviceDatestring (date) | nullrequired
  Date (YYYY-MM-DD)
- servicePeriodServicePeriod | nullrequired
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- serviceDateSource"entered" | "period" | "confirmed_issue_date" | "recurring" | "not_applicable" | nullrequired
  Source of the date of supply (ST-13): confirmed_issue_date = confirmed by the user
- issuanceInvoiceIssuance | nullrequired
  Evidence of issue (from finalising, ST-14)
  - finalizedAtstring (date-time)required
    Server time of finalising
  - serverDatestring (date)required
    Calendar day of finalising (Europe/Berlin)
  - issueDatestring (date)required
    Date (YYYY-MM-DD)
  - issueDateSource"finalize_day" | "entered"required
    finalize_day = day of finalising, entered = entered in the draft
  - deviationDaysintegerrequired
    Issue date minus finalising day in days (negative = earlier)
    -9007199254740991–9007199254740991
  - reasonstring | nullrequired
    Reason for a differing issue date
  - numberstring | nullrequired
  - numberRangestringrequired
    Number range
- dueDatestring (date) | nullrequired
  Date (YYYY-MM-DD)
- paymentTermsDaysintegerrequired
  -9007199254740991–9007199254740991
- priceMode"net" | "gross"required
- taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
  Tax treatment of the receipt
- taxNoticestring | nullrequired
  Mandatory notice (§ 19, § 13b, intra-Community supply …)
- taxCaseInvoiceTaxCase | nullrequired
  Tax case (tax assistant); saved at the latest when finalising
  - factsobjectrequired
  - treatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
    Tax treatment of the receipt
  - placeOfSupplystringrequired
    Place of supply (ISO country)
  - legalBasisstringrequired
  - noticeVariantenum | nullrequired
    Case variant of the mandatory notice (ST-03)
    Values: small_business, reverse_charge, reverse_charge_eu, intra_eu_supply, export, non_taxable, tax_exempt
  - ustvaKzstring | nullrequired
    Advance VAT return form field of the tax base (not for standard taxation)
  - reportingArray<"ustva" | "zm" | "none">required
  - confidence"certain" | "likely" | "review"required
  - assumedbooleanrequired
    Facts assumed from the invoice data (not entered)
  - reasonsArray<string>required
  - warningsArray<string>required
- currency"EUR"required
- subjectstringrequired
- introTextstringrequired
- closingTextstringrequired
- referencestringrequired
- linesArray<DocumentLine>required
  - idstring
    stable line item ID (assigned by the server if empty)
    max. 40 characters
  - type"item" | "text" | "subtotal"
    Line item, plain text line or subtotal
    Default: "item"
  - articleIdstring
    Reference to the article master data
    max. 128 characters
  - titlestringrequired
    max. 300 characters
  - descriptionstring
    max. 5000 characters
  - quantitynumber
    -1000000–1000000 · Default: 1
  - unitstring
    Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
    max. 20 characters
  - unitPriceCentsinteger
    Amount in cents
    -100000000000–100000000000 · Default: 0
  - discountPercentnumber
    0–100
  - taxRatenumber
    Tax rate in per cent (19, 7, 0 …)
    0–100 · Default: 19
  - totalCentsinteger
    Amount in cents
    -100000000000–100000000000
  - servicePeriodobject
  - projectIdstring
    max. 128 characters
  - timeEntryIdsArray<string>
    max. 128 characters
- totalsDocumentTotalsrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - groupsArray<object>required
- deductionsArray<InvoiceDeduction>required
  Final invoice: advance payments actually received and deducted (ST-09)
  - invoiceIdstringrequired
    max. 128 characters
  - numberstringrequired
  - issueDatestring (date)required
    Date (YYYY-MM-DD)
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - groupsArray<object>required
  - invoiceGrossCentsinteger
    Invoice amount of the progress invoice (ST-09)
    -100000000000–100000000000
  - unpaidCentsinteger
    Unreceived remainder of the progress invoice – not deducted (ST-09)
    -100000000000–100000000000
- amountDueCentsintegerrequired
  Amount payable (gross less progress invoices)
  -100000000000–100000000000
- paidCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- creditedCentsintegerrequired
  reduced by invoice corrections (progress invoice: incl. the remainder settled with the final invoice)
  -100000000000–100000000000
- deductedCentsinteger | nullrequired
  Progress invoice: amount received and deducted in the final invoice (ST-09)
  -100000000000–100000000000
- supersededCentsinteger | nullrequired
  Progress invoice: unpaid remainder settled with the final invoice (ST-09)
  -100000000000–100000000000
- openCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- relatedInvoiceIdstring | nullrequired
  max. 128 characters
- advanceInvoiceIdsArray<string>required
  max. 128 characters
- offerIdstring | nullrequired
  max. 128 characters
- projectIdstring | nullrequired
  max. 128 characters
- recurringInvoiceIdstring | nullrequired
  max. 128 characters
- canceledByInvoiceIdstring | nullrequired
  Cancellation invoice for this invoice
  max. 128 characters
- debtIdstring | nullrequired
  Debt in dunning (after handover)
  max. 128 characters
- showGiroCodebooleanrequired
- einvoiceFormat"none" | "zugferd" | "xrechnung"required
- language"de" | "en"required
  Document language (fixed on finalisation)
- dispatchobjectrequired
  - countintegerrequired
    -9007199254740991–9007199254740991
  - lastChannel"email" | "post" | nullrequired
  - lastSentAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
- pdfobject | nullrequired
  archived PDF (after finalisation)
  - sha256stringrequired
  - createdAtstring (date-time)required
    Timestamp (ISO 8601)
- lockedbooleanrequired
- lockedAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
- paidAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
- handedOverAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
- updatedAtstring (date-time)required
  Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/invoices/ID/payments' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "amountCents": 0,
  "date": "2026-11-01",
  "method": "bank",
  "bankTransactionId": "string",
  "note": "string"
}'

Response 201

{
  "payment": {
    "id": "string",
    "invoiceId": "string",
    "amountCents": 0,
    "date": "2026-11-01",
    "method": "bank",
    "bankTransactionId": "string",
    "note": "string",
    "createdAt": "2026-11-01T09:30:00.000Z"
  },
  "invoice": {
    "id": "string",
    "object": "invoice",
    "type": "invoice",
    "kind": "standard",
    "status": "draft",
    "number": "string",
    "contactId": "string",
    "recipient": {
      "name": "string",
      "addition": "string",
      "street": "",
      "zipCode": "",
      "city": "",
      "country": "DE",
      "email": "[email protected]",
      "vatId": "string",
      "leitwegId": "string",
      "einvoiceRecipientType": "business",
      "customerNumber": "string"
    },
    "sender": {
      "companyName": null,
      "ownerName": null,
      "legalForm": null,
      "managingDirectors": null,
      "street": null,
      "zipCode": null,
      "city": null,
      "countryCode": null,
      "phone": null,
      "email": null,
      "website": null,
      "taxNumber": null,
      "vatId": null,
      "smallBusiness": null,
      "commercialRegister": null,
      "bank": null,
      "invoiceFooter": null
    },
    "issueDate": "2026-11-01",
    "serviceDate": "2026-11-01",
    "servicePeriod": {
      "from": null,
      "to": null
    },
    "serviceDateSource": "entered",
    "issuance": {
      "finalizedAt": null,
      "serverDate": null,
      "issueDate": null,
      "issueDateSource": null,
      "deviationDays": null,
      "reason": null,
      "number": null,
      "numberRange": null
    },
    "dueDate": "2026-11-01",
    "paymentTermsDays": 0,
    "priceMode": "net",
    "taxTreatment": "regular",
    "taxNotice": "string",
    "taxCase": {
      "facts": null,
      "treatment": null,
      "placeOfSupply": null,
      "legalBasis": null,
      "noticeVariant": null,
      "ustvaKz": null,
      "reporting": null,
      "confidence": null,
      "assumed": null,
      "reasons": null,
      "warnings": null
    },
    "currency": "EUR",
    "subject": "string",
    "introText": "string",
    "closingText": "string",
    "reference": "string",
    "lines": [
      {
        "id": null,
        "type": null,
        "articleId": null,
        "title": null,
        "description": null,
        "quantity": null,
        "unit": null,
        "unitPriceCents": null,
        "discountPercent": null,
        "taxRate": null,
        "totalCents": null,
        "servicePeriod": null,
        "projectId": null,
        "timeEntryIds": null
      }
    ],
    "totals": {
      "netCents": 0,
      "taxCents": 0,
      "grossCents": 0,
      "groups": [
        null
      ]
    },
    "deductions": [
      {
        "invoiceId": null,
        "number": null,
        "issueDate": null,
        "netCents": null,
        "taxCents": null,
        "grossCents": null,
        "groups": null,
        "invoiceGrossCents": null,
        "unpaidCents": null
      }
    ],
    "amountDueCents": 0,
    "paidCents": 0,
    "creditedCents": 0,
    "deductedCents": 0,
    "supersededCents": 0,
    "openCents": 0,
    "relatedInvoiceId": "string",
    "advanceInvoiceIds": [
      "string"
    ],
    "offerId": "string",
    "projectId": "string",
    "recurringInvoiceId": "string",
    "canceledByInvoiceId": "string",
    "debtId": "string",
    "showGiroCode": false,
    "einvoiceFormat": "none",
    "language": "de",
    "dispatch": {
      "count": 0,
      "lastChannel": "email",
      "lastSentAt": "2026-11-01T09:30:00.000Z"
    },
    "pdf": {
      "sha256": "string",
      "createdAt": "2026-11-01T09:30:00.000Z"
    },
    "locked": false,
    "lockedAt": "2026-11-01T09:30:00.000Z",
    "paidAt": "2026-11-01T09:30:00.000Z",
    "handedOverAt": "2026-11-01T09:30:00.000Z",
    "createdAt": "2026-11-01T09:30:00.000Z",
    "updatedAt": "2026-11-01T09:30:00.000Z"
  }
}

Delete payment

DELETE/api/v1/invoices/{id}/payments/{paymentId}

Removes a payment recorded in error (logged) and returns the invoice with its recalculated status.

Permission: invoices:write

Path parameters

idstringrequired
max. 128 characters
paymentIdstringrequired
max. 128 characters

Response 200 · Invoice

idstringrequired
max. 128 characters
object"invoice"required
type"invoice" | "credit_note" | "cancellation"required
kind"standard" | "advance" | "final"required
status"draft" | "open" | "partially_paid" | "paid" | "overdue" | "canceled"required
numberstring | nullrequired
Document number; assigned only on finalising
contactIdstring | nullrequired
max. 128 characters
recipientDocumentRecipientrequired
- namestringrequired
  Company or name
  max. 160 characters
- additionstring
  Address supplement, e.g. attn. Ms Muster
  max. 160 characters
- streetstringrequired
  max. 160 characters · Default: ""
- zipCodestringrequired
  max. 10 characters · Default: ""
- citystringrequired
  max. 80 characters · Default: ""
- countrystringrequired
  Country code ISO 3166-1 alpha-2
  max. 2 characters · Default: "DE"
- emailstring (email)
  Invoice recipient (email)
  max. 254 characters
- vatIdstring
  Recipient's VAT ID (required for reverse charge/intra-Community supply)
- leitwegIdstring
  Leitweg-ID (XRechnung to public authorities)
  max. 60 characters
- einvoiceRecipientType"business" | "public_authority"
  E-invoice recipient profile (from the contact): public_authority requires a Leitweg-ID (ER-08)
- customerNumberstring
  Customer number (assigned on finalisation)
  max. 40 characters
senderSenderSnapshot | nullrequired
Sender snapshot (taken on finalising)
- companyNamestringrequired
- ownerNamestring
- legalFormstring
- managingDirectorsstring
- streetstringrequired
- zipCodestringrequired
- citystringrequired
- countryCodestringrequired
- phonestring
- emailstring
- websitestring
- taxNumberstring
- vatIdstring
- smallBusinessbooleanrequired
- commercialRegisterobject
  - courtstring
  - numberstring
- bankobject
  - accountHolderstring
  - ibanstring
  - bicstring
  - bankNamestring
- invoiceFooterstring
issueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
serviceDatestring (date) | nullrequired
Date (YYYY-MM-DD)
servicePeriodServicePeriod | nullrequired
- fromstring (date)required
  Date (YYYY-MM-DD)
- tostring (date)required
  Date (YYYY-MM-DD)
serviceDateSource"entered" | "period" | "confirmed_issue_date" | "recurring" | "not_applicable" | nullrequired
Source of the date of supply (ST-13): confirmed_issue_date = confirmed by the user
issuanceInvoiceIssuance | nullrequired
Evidence of issue (from finalising, ST-14)
- finalizedAtstring (date-time)required
  Server time of finalising
- serverDatestring (date)required
  Calendar day of finalising (Europe/Berlin)
- issueDatestring (date)required
  Date (YYYY-MM-DD)
- issueDateSource"finalize_day" | "entered"required
  finalize_day = day of finalising, entered = entered in the draft
- deviationDaysintegerrequired
  Issue date minus finalising day in days (negative = earlier)
  -9007199254740991–9007199254740991
- reasonstring | nullrequired
  Reason for a differing issue date
- numberstring | nullrequired
- numberRangestringrequired
  Number range
dueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
paymentTermsDaysintegerrequired
-9007199254740991–9007199254740991
priceMode"net" | "gross"required
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
Tax treatment of the receipt
taxNoticestring | nullrequired
Mandatory notice (§ 19, § 13b, intra-Community supply …)
taxCaseInvoiceTaxCase | nullrequired
Tax case (tax assistant); saved at the latest when finalising
- factsobjectrequired
  - kind"goods" | "service" | "construction" | "property_service" | "electronic_service"required
    Type of supply
  - smallBusinessbooleanrequired
  - customerCountrystringrequired
    Country of residence of the recipient
    max. 2 characters
  - customerIsBusinessbooleanrequired
    Recipient is a business and receives the supply for its business
  - customerVatIdValidbooleanrequired
    a valid VAT ID of the recipient is available
  - destinationCountrystring | null
    Supply of goods: country of destination
    max. 2 characters
  - propertyCountrystring | null
    Service related to real estate: location of the property
    max. 2 characters
  - exemption"§ 4 Nr. 8 UStG" | "§ 4 Nr. 11 UStG" | "§ 4 Nr. 12 UStG" | "§ 4 Nr. 14 UStG" | "§ 4 Nr. 21 UStG" | "other" | null
    VAT exemption without input VAT deduction
- treatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
  Tax treatment of the receipt
- placeOfSupplystringrequired
  Place of supply (ISO country)
- legalBasisstringrequired
- noticeVariantenum | nullrequired
  Case variant of the mandatory notice (ST-03)
  Values: small_business, reverse_charge, reverse_charge_eu, intra_eu_supply, export, non_taxable, tax_exempt
- ustvaKzstring | nullrequired
  Advance VAT return form field of the tax base (not for standard taxation)
- reportingArray<"ustva" | "zm" | "none">required
- confidence"certain" | "likely" | "review"required
- assumedbooleanrequired
  Facts assumed from the invoice data (not entered)
- reasonsArray<string>required
- warningsArray<string>required
currency"EUR"required
subjectstringrequired
introTextstringrequired
closingTextstringrequired
referencestringrequired
linesArray<DocumentLine>required
- idstring
  stable line item ID (assigned by the server if empty)
  max. 40 characters
- type"item" | "text" | "subtotal"
  Line item, plain text line or subtotal
  Default: "item"
- articleIdstring
  Reference to the article master data
  max. 128 characters
- titlestringrequired
  max. 300 characters
- descriptionstring
  max. 5000 characters
- quantitynumber
  -1000000–1000000 · Default: 1
- unitstring
  Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
  max. 20 characters
- unitPriceCentsinteger
  Amount in cents
  -100000000000–100000000000 · Default: 0
- discountPercentnumber
  0–100
- taxRatenumber
  Tax rate in per cent (19, 7, 0 …)
  0–100 · Default: 19
- totalCentsinteger
  Amount in cents
  -100000000000–100000000000
- servicePeriodobject
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- projectIdstring
  max. 128 characters
- timeEntryIdsArray<string>
  max. 128 characters
totalsDocumentTotalsrequired
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - categorystringrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
deductionsArray<InvoiceDeduction>required
Final invoice: advance payments actually received and deducted (ST-09)
- invoiceIdstringrequired
  max. 128 characters
- numberstringrequired
- issueDatestring (date)required
  Date (YYYY-MM-DD)
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
- invoiceGrossCentsinteger
  Invoice amount of the progress invoice (ST-09)
  -100000000000–100000000000
- unpaidCentsinteger
  Unreceived remainder of the progress invoice – not deducted (ST-09)
  -100000000000–100000000000
amountDueCentsintegerrequired
Amount payable (gross less progress invoices)
-100000000000–100000000000
paidCentsintegerrequired
Amount in cents
-100000000000–100000000000
creditedCentsintegerrequired
reduced by invoice corrections (progress invoice: incl. the remainder settled with the final invoice)
-100000000000–100000000000
deductedCentsinteger | nullrequired
Progress invoice: amount received and deducted in the final invoice (ST-09)
-100000000000–100000000000
supersededCentsinteger | nullrequired
Progress invoice: unpaid remainder settled with the final invoice (ST-09)
-100000000000–100000000000
openCentsintegerrequired
Amount in cents
-100000000000–100000000000
relatedInvoiceIdstring | nullrequired
max. 128 characters
advanceInvoiceIdsArray<string>required
max. 128 characters
offerIdstring | nullrequired
max. 128 characters
projectIdstring | nullrequired
max. 128 characters
recurringInvoiceIdstring | nullrequired
max. 128 characters
canceledByInvoiceIdstring | nullrequired
Cancellation invoice for this invoice
max. 128 characters
debtIdstring | nullrequired
Debt in dunning (after handover)
max. 128 characters
showGiroCodebooleanrequired
einvoiceFormat"none" | "zugferd" | "xrechnung"required
language"de" | "en"required
Document language (fixed on finalisation)
dispatchobjectrequired
- countintegerrequired
  -9007199254740991–9007199254740991
- lastChannel"email" | "post" | nullrequired
- lastSentAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
pdfobject | nullrequired
archived PDF (after finalisation)
- sha256stringrequired
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
lockedbooleanrequired
lockedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
paidAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
handedOverAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 429, 500

curl -X DELETE 'https://www.debt-flow.io/api/v1/invoices/ID/payments/PAYMENTID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "id": "string",
  "object": "invoice",
  "type": "invoice",
  "kind": "standard",
  "status": "draft",
  "number": "string",
  "contactId": "string",
  "recipient": {
    "name": "string",
    "addition": "string",
    "street": "",
    "zipCode": "",
    "city": "",
    "country": "DE",
    "email": "[email protected]",
    "vatId": "string",
    "leitwegId": "string",
    "einvoiceRecipientType": "business",
    "customerNumber": "string"
  },
  "sender": {
    "companyName": "string",
    "ownerName": "string",
    "legalForm": "string",
    "managingDirectors": "string",
    "street": "string",
    "zipCode": "string",
    "city": "string",
    "countryCode": "string",
    "phone": "string",
    "email": "string",
    "website": "string",
    "taxNumber": "string",
    "vatId": "string",
    "smallBusiness": false,
    "commercialRegister": {
      "court": "string",
      "number": "string"
    },
    "bank": {
      "accountHolder": "string",
      "iban": "string",
      "bic": "string",
      "bankName": "string"
    },
    "invoiceFooter": "string"
  },
  "issueDate": "2026-11-01",
  "serviceDate": "2026-11-01",
  "servicePeriod": {
    "from": "2026-11-01",
    "to": "2026-11-01"
  },
  "serviceDateSource": "entered",
  "issuance": {
    "finalizedAt": "2026-11-01T09:30:00.000Z",
    "serverDate": "2026-11-01",
    "issueDate": "2026-11-01",
    "issueDateSource": "finalize_day",
    "deviationDays": 0,
    "reason": "string",
    "number": "string",
    "numberRange": "string"
  },
  "dueDate": "2026-11-01",
  "paymentTermsDays": 0,
  "priceMode": "net",
  "taxTreatment": "regular",
  "taxNotice": "string",
  "taxCase": {
    "facts": {
      "kind": "goods",
      "smallBusiness": false,
      "customerCountry": "string",
      "customerIsBusiness": false,
      "customerVatIdValid": false,
      "destinationCountry": null,
      "propertyCountry": null,
      "exemption": null
    },
    "treatment": "regular",
    "placeOfSupply": "string",
    "legalBasis": "string",
    "noticeVariant": "small_business",
    "ustvaKz": "string",
    "reporting": [
      "ustva"
    ],
    "confidence": "certain",
    "assumed": false,
    "reasons": [
      "string"
    ],
    "warnings": [
      "string"
    ]
  },
  "currency": "EUR",
  "subject": "string",
  "introText": "string",
  "closingText": "string",
  "reference": "string",
  "lines": [
    {
      "id": "string",
      "type": "item",
      "articleId": "string",
      "title": "string",
      "description": "string",
      "quantity": 1,
      "unit": "string",
      "unitPriceCents": 0,
      "discountPercent": 0,
      "taxRate": 19,
      "totalCents": 0,
      "servicePeriod": {
        "from": "2026-11-01",
        "to": "2026-11-01"
      },
      "projectId": "string",
      "timeEntryIds": [
        "string"
      ]
    }
  ],
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0,
    "groups": [
      {
        "taxRate": 0,
        "category": "string",
        "netCents": 0,
        "taxCents": 0,
        "grossCents": 0
      }
    ]
  },
  "deductions": [
    {
      "invoiceId": "string",
      "number": "string",
      "issueDate": "2026-11-01",
      "netCents": 0,
      "taxCents": 0,
      "grossCents": 0,
      "groups": [
        {
          "taxRate": null,
          "netCents": null,
          "taxCents": null
        }
      ],
      "invoiceGrossCents": 0,
      "unpaidCents": 0
    }
  ],
  "amountDueCents": 0,
  "paidCents": 0,
  "creditedCents": 0,
  "deductedCents": 0,
  "supersededCents": 0,
  "openCents": 0,
  "relatedInvoiceId": "string",
  "advanceInvoiceIds": [
    "string"
  ],
  "offerId": "string",
  "projectId": "string",
  "recurringInvoiceId": "string",
  "canceledByInvoiceId": "string",
  "debtId": "string",
  "showGiroCode": false,
  "einvoiceFormat": "none",
  "language": "de",
  "dispatch": {
    "count": 0,
    "lastChannel": "email",
    "lastSentAt": "2026-11-01T09:30:00.000Z"
  },
  "pdf": {
    "sha256": "string",
    "createdAt": "2026-11-01T09:30:00.000Z"
  },
  "locked": false,
  "lockedAt": "2026-11-01T09:30:00.000Z",
  "paidAt": "2026-11-01T09:30:00.000Z",
  "handedOverAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Invoice as PDF

GET/api/v1/invoices/{id}/pdf

Finalised documents: the unaltered PDF archived on first retrieval (SHA-256 in pdf.sha256). Drafts: preview marked “Draft”.

Permission: invoices:read

Path parameters

idstringrequired
Resource ID
max. 128 characters

Response 200

File (application/pdf).

Possible errors: 400, 401, 403, 404, 409, 429, 500

curl 'https://www.debt-flow.io/api/v1/invoices/ID/pdf' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Send invoice (email or post)

POST/api/v1/invoices/{id}/send

channel: email sends the PDF as an attachment on behalf of your company (replies go to your invoicing email address). channel: post prints and sends the PDF via Briefdiener (chargeable or from the monthly quota, optionally as registered mail) and additionally requires the scope letters:write. Finalised documents only; with finalize: true, a draft is finalised first.

Permission: invoices:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Headers

Idempotency-Keystring
Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
max. 255 characters

Body (JSON) · InvoiceSend

channel"email" | "post"required
toArray<string (email)>
Email: recipient; default is the contact's invoice email address
max. 254 characters
ccArray<string (email)>
max. 254 characters
copyToSelfboolean
Email: copy to your own invoice email address
subjectstring
max. 200 characters
messagestring
Email body; placeholders {nummer} {betrag} {faellig} {kunde} {firma}
max. 5000 characters
registeredboolean
Post: as registered mail
finalizeboolean
Finalise the draft before sending
confirmServiceDateboolean
Without a date or period of supply: confirms that the supply was made on the invoice date (§ 14 (4) No. 6 UStG)
issueDateReasonstring
Reason if the invoice date differs from the day of finalising (will be logged)
max. 500 characters

Response 201 · InvoiceDispatch

idstringrequired
max. 128 characters
invoiceIdstringrequired
max. 128 characters
channel"email" | "post"required
status"sending" | "sent" | "failed"required
toArray<string>required
subjectstring | nullrequired
registeredbooleanrequired
letterIdstring | nullrequired
trackingRefstring | nullrequired
pageCountinteger | nullrequired
-9007199254740991–9007199254740991
priceEurostring | nullrequired
deliveryStatus"pending" | "delivered" | "failed" | "returned" | nullrequired
Post only: delivery status according to Briefdiener (cron letter-status), otherwise null
deliveryMessagestring | nullrequired
trackingUrlstring | nullrequired
deliveryUpdatedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
errorstring | nullrequired
actorActor | nullrequired
- type"user" | "api_key" | "oauth" | "system"required
- idstringrequired
- labelstring
createdAtstring (date-time)required
Timestamp (ISO 8601)
sentAtstring (date-time) | nullrequired
Timestamp (ISO 8601)

Possible errors: 400, 401, 402, 403, 404, 409, 422, 429, 500, 502

curl -X POST 'https://www.debt-flow.io/api/v1/invoices/ID/send' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "channel": "email",
  "to": [
    "[email protected]"
  ],
  "cc": [
    "[email protected]"
  ],
  "copyToSelf": false,
  "subject": "string",
  "message": "string",
  "registered": false,
  "finalize": false,
  "confirmServiceDate": false,
  "issueDateReason": "string"
}'

Response 201

{
  "id": "string",
  "invoiceId": "string",
  "channel": "email",
  "status": "sending",
  "to": [
    "string"
  ],
  "subject": "string",
  "registered": false,
  "letterId": "string",
  "trackingRef": "string",
  "pageCount": 0,
  "priceEuro": "string",
  "deliveryStatus": "pending",
  "deliveryMessage": "string",
  "trackingUrl": "string",
  "deliveryUpdatedAt": "2026-11-01T09:30:00.000Z",
  "error": "string",
  "actor": {
    "type": "user",
    "id": "string",
    "label": "string"
  },
  "createdAt": "2026-11-01T09:30:00.000Z",
  "sentAt": "2026-11-01T09:30:00.000Z"
}

Open invoices overview

GET/api/v1/invoices/summary

Number of drafts, plus the number and outstanding amount of open and overdue invoices.

Permission: invoices:read

Response 200 · InvoiceSummary

draftobjectrequired
- countintegerrequired
  -9007199254740991–9007199254740991
openobjectrequired
- countintegerrequired
  -9007199254740991–9007199254740991
- openCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
overdueobjectrequired
- countintegerrequired
  -9007199254740991–9007199254740991
- openCentsintegerrequired
  Amount in cents
  -100000000000–100000000000

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/invoices/summary' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "draft": {
    "count": 0
  },
  "open": {
    "count": 0,
    "openCents": 0
  },
  "overdue": {
    "count": 0,
    "openCents": 0
  }
}

List recurring invoices

GET/api/v1/recurring-invoices

Permission: invoices:read

Query parameters

limitinteger
Number of entries (1–100)
1–100 · Default: 25
cursorstring
`nextCursor` of the previous page
max. 500 characters

Response 200

object"list"required
dataArray<RecurringInvoice>required
- idstringrequired
  max. 128 characters
- object"recurring_invoice"required
- namestringrequired
- activebooleanrequired
- contactIdstringrequired
  max. 128 characters
- interval"weekly" | "monthly" | "quarterly" | "half_yearly" | "yearly"required
- nextRunDatestring (date)required
  Date (YYYY-MM-DD)
- endDatestring (date) | nullrequired
  Date (YYYY-MM-DD)
- servicePeriodMode"none" | "current_period" | "previous_period"required
- autoFinalizebooleanrequired
- autoSendbooleanrequired
- priceMode"net" | "gross" | nullrequired
- taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable" | nullrequired
  Tax treatment of the receipt
- paymentTermsDaysinteger | nullrequired
  -9007199254740991–9007199254740991
- subjectstringrequired
- introTextstringrequired
- closingTextstringrequired
- referencestringrequired
- linesArray<DocumentLine>required
  - idstring
    stable line item ID (assigned by the server if empty)
    max. 40 characters
  - type"item" | "text" | "subtotal"
    Line item, plain text line or subtotal
    Default: "item"
  - articleIdstring
    Reference to the article master data
    max. 128 characters
  - titlestringrequired
    max. 300 characters
  - descriptionstring
    max. 5000 characters
  - quantitynumber
    -1000000–1000000 · Default: 1
  - unitstring
    Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
    max. 20 characters
  - unitPriceCentsinteger
    Amount in cents
    -100000000000–100000000000 · Default: 0
  - discountPercentnumber
    0–100
  - taxRatenumber
    Tax rate in per cent (19, 7, 0 …)
    0–100 · Default: 19
  - totalCentsinteger
    Amount in cents
    -100000000000–100000000000
  - servicePeriodobject
  - projectIdstring
    max. 128 characters
  - timeEntryIdsArray<string>
    max. 128 characters
- totalsDocumentTotalsrequired
  Preview with the current line items
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - groupsArray<object>required
- invoiceCountintegerrequired
  -9007199254740991–9007199254740991
- lastRunAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
- lastInvoiceIdstring | nullrequired
  max. 128 characters
- lastErrorstring | nullrequired
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
- updatedAtstring (date-time)required
  Timestamp (ISO 8601)
hasMorebooleanrequired
nextCursorstring | nullrequired

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/recurring-invoices' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "recurring_invoice",
      "name": "string",
      "active": false,
      "contactId": "string",
      "interval": "weekly",
      "nextRunDate": "2026-11-01",
      "endDate": "2026-11-01",
      "servicePeriodMode": "none",
      "autoFinalize": false,
      "autoSend": false,
      "priceMode": "net",
      "taxTreatment": "regular",
      "paymentTermsDays": 0,
      "subject": "string",
      "introText": "string",
      "closingText": "string",
      "reference": "string",
      "lines": [
        {
          "id": null,
          "type": null,
          "articleId": null,
          "title": null,
          "description": null,
          "quantity": null,
          "unit": null,
          "unitPriceCents": null,
          "discountPercent": null,
          "taxRate": null,
          "totalCents": null,
          "servicePeriod": null,
          "projectId": null,
          "timeEntryIds": null
        }
      ],
      "totals": {
        "netCents": 0,
        "taxCents": 0,
        "grossCents": 0,
        "groups": [
          null
        ]
      },
      "invoiceCount": 0,
      "lastRunAt": "2026-11-01T09:30:00.000Z",
      "lastInvoiceId": "string",
      "lastError": "string",
      "createdAt": "2026-11-01T09:30:00.000Z",
      "updatedAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Create recurring invoice

POST/api/v1/recurring-invoices

Template with customer, line items and interval. The daily run generates an invoice on the scheduled date (draft or finalised, optionally sent by email). Placeholders in subject/introduction/line items: {zeitraum} {monat} {jahr}.

Permission: invoices:write

Headers

Idempotency-Keystring
Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
max. 255 characters

Body (JSON) · RecurringInvoiceCreate

namestringrequired
max. 120 characters
activeboolean
Default: true
contactIdstringrequired
max. 128 characters
interval"weekly" | "monthly" | "quarterly" | "half_yearly" | "yearly"required
nextRunDatestring (date)required
Next invoice date
endDatestring (date) | null
last possible invoice date (empty = unlimited)
servicePeriodMode"none" | "current_period" | "previous_period"
Default: "none"
autoFinalizeboolean
Finalise invoice immediately (otherwise draft for review)
Default: false
autoSendboolean
send finalised invoice by email
Default: false
priceMode"net" | "gross"
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"
Tax treatment of the receipt
paymentTermsDaysinteger
0–365
subjectstring
Placeholders {zeitraum} {monat} {jahr}
max. 200 characters
introTextstring
max. 5000 characters
closingTextstring
max. 5000 characters
referencestring
max. 100 characters
linesArray<DocumentLine>required
- idstring
  stable line item ID (assigned by the server if empty)
  max. 40 characters
- type"item" | "text" | "subtotal"
  Line item, plain text line or subtotal
  Default: "item"
- articleIdstring
  Reference to the article master data
  max. 128 characters
- titlestringrequired
  max. 300 characters
- descriptionstring
  max. 5000 characters
- quantitynumber
  -1000000–1000000 · Default: 1
- unitstring
  Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
  max. 20 characters
- unitPriceCentsinteger
  Amount in cents
  -100000000000–100000000000 · Default: 0
- discountPercentnumber
  0–100
- taxRatenumber
  Tax rate in per cent (19, 7, 0 …)
  0–100 · Default: 19
- totalCentsinteger
  Amount in cents
  -100000000000–100000000000
- servicePeriodobject
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- projectIdstring
  max. 128 characters
- timeEntryIdsArray<string>
  max. 128 characters

Response 201 · RecurringInvoice

idstringrequired
max. 128 characters
object"recurring_invoice"required
namestringrequired
activebooleanrequired
contactIdstringrequired
max. 128 characters
interval"weekly" | "monthly" | "quarterly" | "half_yearly" | "yearly"required
nextRunDatestring (date)required
Date (YYYY-MM-DD)
endDatestring (date) | nullrequired
Date (YYYY-MM-DD)
servicePeriodMode"none" | "current_period" | "previous_period"required
autoFinalizebooleanrequired
autoSendbooleanrequired
priceMode"net" | "gross" | nullrequired
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable" | nullrequired
Tax treatment of the receipt
paymentTermsDaysinteger | nullrequired
-9007199254740991–9007199254740991
subjectstringrequired
introTextstringrequired
closingTextstringrequired
referencestringrequired
linesArray<DocumentLine>required
- idstring
  stable line item ID (assigned by the server if empty)
  max. 40 characters
- type"item" | "text" | "subtotal"
  Line item, plain text line or subtotal
  Default: "item"
- articleIdstring
  Reference to the article master data
  max. 128 characters
- titlestringrequired
  max. 300 characters
- descriptionstring
  max. 5000 characters
- quantitynumber
  -1000000–1000000 · Default: 1
- unitstring
  Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
  max. 20 characters
- unitPriceCentsinteger
  Amount in cents
  -100000000000–100000000000 · Default: 0
- discountPercentnumber
  0–100
- taxRatenumber
  Tax rate in per cent (19, 7, 0 …)
  0–100 · Default: 19
- totalCentsinteger
  Amount in cents
  -100000000000–100000000000
- servicePeriodobject
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- projectIdstring
  max. 128 characters
- timeEntryIdsArray<string>
  max. 128 characters
totalsDocumentTotalsrequired
Preview with the current line items
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - categorystringrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
invoiceCountintegerrequired
-9007199254740991–9007199254740991
lastRunAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
lastInvoiceIdstring | nullrequired
max. 128 characters
lastErrorstring | nullrequired
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/recurring-invoices' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "active": true,
  "contactId": "string",
  "interval": "weekly",
  "nextRunDate": "2026-11-01",
  "endDate": "2026-11-01",
  "servicePeriodMode": "none",
  "autoFinalize": false,
  "autoSend": false,
  "priceMode": "net",
  "taxTreatment": "regular",
  "paymentTermsDays": 0,
  "subject": "string",
  "introText": "string",
  "closingText": "string",
  "reference": "string",
  "lines": [
    {
      "id": "string",
      "type": "item",
      "articleId": "string",
      "title": "string",
      "description": "string",
      "quantity": 1,
      "unit": "string",
      "unitPriceCents": 0,
      "discountPercent": 0,
      "taxRate": 19,
      "totalCents": 0,
      "servicePeriod": {
        "from": "2026-11-01",
        "to": "2026-11-01"
      },
      "projectId": "string",
      "timeEntryIds": [
        "string"
      ]
    }
  ]
}'

Response 201

{
  "id": "string",
  "object": "recurring_invoice",
  "name": "string",
  "active": false,
  "contactId": "string",
  "interval": "weekly",
  "nextRunDate": "2026-11-01",
  "endDate": "2026-11-01",
  "servicePeriodMode": "none",
  "autoFinalize": false,
  "autoSend": false,
  "priceMode": "net",
  "taxTreatment": "regular",
  "paymentTermsDays": 0,
  "subject": "string",
  "introText": "string",
  "closingText": "string",
  "reference": "string",
  "lines": [
    {
      "id": "string",
      "type": "item",
      "articleId": "string",
      "title": "string",
      "description": "string",
      "quantity": 1,
      "unit": "string",
      "unitPriceCents": 0,
      "discountPercent": 0,
      "taxRate": 19,
      "totalCents": 0,
      "servicePeriod": {
        "from": "2026-11-01",
        "to": "2026-11-01"
      },
      "projectId": "string",
      "timeEntryIds": [
        "string"
      ]
    }
  ],
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0,
    "groups": [
      {
        "taxRate": 0,
        "category": "string",
        "netCents": 0,
        "taxCents": 0,
        "grossCents": 0
      }
    ]
  },
  "invoiceCount": 0,
  "lastRunAt": "2026-11-01T09:30:00.000Z",
  "lastInvoiceId": "string",
  "lastError": "string",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Retrieve recurring invoice

GET/api/v1/recurring-invoices/{id}

Permission: invoices:read

Path parameters

idstringrequired
Resource ID
max. 128 characters

Response 200 · RecurringInvoice

idstringrequired
max. 128 characters
object"recurring_invoice"required
namestringrequired
activebooleanrequired
contactIdstringrequired
max. 128 characters
interval"weekly" | "monthly" | "quarterly" | "half_yearly" | "yearly"required
nextRunDatestring (date)required
Date (YYYY-MM-DD)
endDatestring (date) | nullrequired
Date (YYYY-MM-DD)
servicePeriodMode"none" | "current_period" | "previous_period"required
autoFinalizebooleanrequired
autoSendbooleanrequired
priceMode"net" | "gross" | nullrequired
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable" | nullrequired
Tax treatment of the receipt
paymentTermsDaysinteger | nullrequired
-9007199254740991–9007199254740991
subjectstringrequired
introTextstringrequired
closingTextstringrequired
referencestringrequired
linesArray<DocumentLine>required
- idstring
  stable line item ID (assigned by the server if empty)
  max. 40 characters
- type"item" | "text" | "subtotal"
  Line item, plain text line or subtotal
  Default: "item"
- articleIdstring
  Reference to the article master data
  max. 128 characters
- titlestringrequired
  max. 300 characters
- descriptionstring
  max. 5000 characters
- quantitynumber
  -1000000–1000000 · Default: 1
- unitstring
  Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
  max. 20 characters
- unitPriceCentsinteger
  Amount in cents
  -100000000000–100000000000 · Default: 0
- discountPercentnumber
  0–100
- taxRatenumber
  Tax rate in per cent (19, 7, 0 …)
  0–100 · Default: 19
- totalCentsinteger
  Amount in cents
  -100000000000–100000000000
- servicePeriodobject
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- projectIdstring
  max. 128 characters
- timeEntryIdsArray<string>
  max. 128 characters
totalsDocumentTotalsrequired
Preview with the current line items
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - categorystringrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
invoiceCountintegerrequired
-9007199254740991–9007199254740991
lastRunAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
lastInvoiceIdstring | nullrequired
max. 128 characters
lastErrorstring | nullrequired
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/recurring-invoices/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 200

{
  "id": "string",
  "object": "recurring_invoice",
  "name": "string",
  "active": false,
  "contactId": "string",
  "interval": "weekly",
  "nextRunDate": "2026-11-01",
  "endDate": "2026-11-01",
  "servicePeriodMode": "none",
  "autoFinalize": false,
  "autoSend": false,
  "priceMode": "net",
  "taxTreatment": "regular",
  "paymentTermsDays": 0,
  "subject": "string",
  "introText": "string",
  "closingText": "string",
  "reference": "string",
  "lines": [
    {
      "id": "string",
      "type": "item",
      "articleId": "string",
      "title": "string",
      "description": "string",
      "quantity": 1,
      "unit": "string",
      "unitPriceCents": 0,
      "discountPercent": 0,
      "taxRate": 19,
      "totalCents": 0,
      "servicePeriod": {
        "from": "2026-11-01",
        "to": "2026-11-01"
      },
      "projectId": "string",
      "timeEntryIds": [
        "string"
      ]
    }
  ],
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0,
    "groups": [
      {
        "taxRate": 0,
        "category": "string",
        "netCents": 0,
        "taxCents": 0,
        "grossCents": 0
      }
    ]
  },
  "invoiceCount": 0,
  "lastRunAt": "2026-11-01T09:30:00.000Z",
  "lastInvoiceId": "string",
  "lastError": "string",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Update recurring invoice

PATCH/api/v1/recurring-invoices/{id}

Changes apply from the next scheduled date. active: false pauses the template.

Permission: invoices:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Body (JSON) · RecurringInvoiceUpdate

namestring
max. 120 characters
activeboolean
contactIdstring
max. 128 characters
interval"weekly" | "monthly" | "quarterly" | "half_yearly" | "yearly"
nextRunDatestring (date)
Next invoice date
endDatestring (date) | null
last possible invoice date (empty = unlimited)
servicePeriodMode"none" | "current_period" | "previous_period"
autoFinalizeboolean
Finalise invoice immediately (otherwise draft for review)
autoSendboolean
send finalised invoice by email
priceMode"net" | "gross"
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"
Tax treatment of the receipt
paymentTermsDaysinteger
0–365
subjectstring
Placeholders {zeitraum} {monat} {jahr}
max. 200 characters
introTextstring
max. 5000 characters
closingTextstring
max. 5000 characters
referencestring
max. 100 characters
linesArray<DocumentLine>
- idstring
  stable line item ID (assigned by the server if empty)
  max. 40 characters
- type"item" | "text" | "subtotal"
  Line item, plain text line or subtotal
  Default: "item"
- articleIdstring
  Reference to the article master data
  max. 128 characters
- titlestringrequired
  max. 300 characters
- descriptionstring
  max. 5000 characters
- quantitynumber
  -1000000–1000000 · Default: 1
- unitstring
  Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
  max. 20 characters
- unitPriceCentsinteger
  Amount in cents
  -100000000000–100000000000 · Default: 0
- discountPercentnumber
  0–100
- taxRatenumber
  Tax rate in per cent (19, 7, 0 …)
  0–100 · Default: 19
- totalCentsinteger
  Amount in cents
  -100000000000–100000000000
- servicePeriodobject
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- projectIdstring
  max. 128 characters
- timeEntryIdsArray<string>
  max. 128 characters

Response 200 · RecurringInvoice

idstringrequired
max. 128 characters
object"recurring_invoice"required
namestringrequired
activebooleanrequired
contactIdstringrequired
max. 128 characters
interval"weekly" | "monthly" | "quarterly" | "half_yearly" | "yearly"required
nextRunDatestring (date)required
Date (YYYY-MM-DD)
endDatestring (date) | nullrequired
Date (YYYY-MM-DD)
servicePeriodMode"none" | "current_period" | "previous_period"required
autoFinalizebooleanrequired
autoSendbooleanrequired
priceMode"net" | "gross" | nullrequired
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable" | nullrequired
Tax treatment of the receipt
paymentTermsDaysinteger | nullrequired
-9007199254740991–9007199254740991
subjectstringrequired
introTextstringrequired
closingTextstringrequired
referencestringrequired
linesArray<DocumentLine>required
- idstring
  stable line item ID (assigned by the server if empty)
  max. 40 characters
- type"item" | "text" | "subtotal"
  Line item, plain text line or subtotal
  Default: "item"
- articleIdstring
  Reference to the article master data
  max. 128 characters
- titlestringrequired
  max. 300 characters
- descriptionstring
  max. 5000 characters
- quantitynumber
  -1000000–1000000 · Default: 1
- unitstring
  Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
  max. 20 characters
- unitPriceCentsinteger
  Amount in cents
  -100000000000–100000000000 · Default: 0
- discountPercentnumber
  0–100
- taxRatenumber
  Tax rate in per cent (19, 7, 0 …)
  0–100 · Default: 19
- totalCentsinteger
  Amount in cents
  -100000000000–100000000000
- servicePeriodobject
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- projectIdstring
  max. 128 characters
- timeEntryIdsArray<string>
  max. 128 characters
totalsDocumentTotalsrequired
Preview with the current line items
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - categorystringrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
invoiceCountintegerrequired
-9007199254740991–9007199254740991
lastRunAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
lastInvoiceIdstring | nullrequired
max. 128 characters
lastErrorstring | nullrequired
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 429, 500

curl -X PATCH 'https://www.debt-flow.io/api/v1/recurring-invoices/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "active": false,
  "contactId": "string",
  "interval": "weekly",
  "nextRunDate": "2026-11-01",
  "endDate": "2026-11-01",
  "servicePeriodMode": "none",
  "autoFinalize": false,
  "autoSend": false,
  "priceMode": "net",
  "taxTreatment": "regular",
  "paymentTermsDays": 0,
  "subject": "string",
  "introText": "string",
  "closingText": "string",
  "reference": "string",
  "lines": [
    {
      "id": "string",
      "type": "item",
      "articleId": "string",
      "title": "string",
      "description": "string",
      "quantity": 1,
      "unit": "string",
      "unitPriceCents": 0,
      "discountPercent": 0,
      "taxRate": 19,
      "totalCents": 0,
      "servicePeriod": {
        "from": "2026-11-01",
        "to": "2026-11-01"
      },
      "projectId": "string",
      "timeEntryIds": [
        "string"
      ]
    }
  ]
}'

Response 200

{
  "id": "string",
  "object": "recurring_invoice",
  "name": "string",
  "active": false,
  "contactId": "string",
  "interval": "weekly",
  "nextRunDate": "2026-11-01",
  "endDate": "2026-11-01",
  "servicePeriodMode": "none",
  "autoFinalize": false,
  "autoSend": false,
  "priceMode": "net",
  "taxTreatment": "regular",
  "paymentTermsDays": 0,
  "subject": "string",
  "introText": "string",
  "closingText": "string",
  "reference": "string",
  "lines": [
    {
      "id": "string",
      "type": "item",
      "articleId": "string",
      "title": "string",
      "description": "string",
      "quantity": 1,
      "unit": "string",
      "unitPriceCents": 0,
      "discountPercent": 0,
      "taxRate": 19,
      "totalCents": 0,
      "servicePeriod": {
        "from": "2026-11-01",
        "to": "2026-11-01"
      },
      "projectId": "string",
      "timeEntryIds": [
        "string"
      ]
    }
  ],
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0,
    "groups": [
      {
        "taxRate": 0,
        "category": "string",
        "netCents": 0,
        "taxCents": 0,
        "grossCents": 0
      }
    ]
  },
  "invoiceCount": 0,
  "lastRunAt": "2026-11-01T09:30:00.000Z",
  "lastInvoiceId": "string",
  "lastError": "string",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Delete recurring invoice

DELETE/api/v1/recurring-invoices/{id}

Invoices that have already been generated are kept.

Permission: invoices:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Response 204

Success, no content

Possible errors: 400, 401, 403, 404, 429, 500

curl -X DELETE 'https://www.debt-flow.io/api/v1/recurring-invoices/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Generate next invoice now

POST/api/v1/recurring-invoices/{id}/run

Generates the invoice for the next scheduled date immediately and advances the template to the following date.

Permission: invoices:write

Path parameters

idstringrequired
Resource ID
max. 128 characters

Headers

Idempotency-Keystring
Unique key (8–255 characters). Repeated requests with the same key return the same response for 24 h.
max. 255 characters

Response 201 · Invoice

idstringrequired
max. 128 characters
object"invoice"required
type"invoice" | "credit_note" | "cancellation"required
kind"standard" | "advance" | "final"required
status"draft" | "open" | "partially_paid" | "paid" | "overdue" | "canceled"required
numberstring | nullrequired
Document number; assigned only on finalising
contactIdstring | nullrequired
max. 128 characters
recipientDocumentRecipientrequired
- namestringrequired
  Company or name
  max. 160 characters
- additionstring
  Address supplement, e.g. attn. Ms Muster
  max. 160 characters
- streetstringrequired
  max. 160 characters · Default: ""
- zipCodestringrequired
  max. 10 characters · Default: ""
- citystringrequired
  max. 80 characters · Default: ""
- countrystringrequired
  Country code ISO 3166-1 alpha-2
  max. 2 characters · Default: "DE"
- emailstring (email)
  Invoice recipient (email)
  max. 254 characters
- vatIdstring
  Recipient's VAT ID (required for reverse charge/intra-Community supply)
- leitwegIdstring
  Leitweg-ID (XRechnung to public authorities)
  max. 60 characters
- einvoiceRecipientType"business" | "public_authority"
  E-invoice recipient profile (from the contact): public_authority requires a Leitweg-ID (ER-08)
- customerNumberstring
  Customer number (assigned on finalisation)
  max. 40 characters
senderSenderSnapshot | nullrequired
Sender snapshot (taken on finalising)
- companyNamestringrequired
- ownerNamestring
- legalFormstring
- managingDirectorsstring
- streetstringrequired
- zipCodestringrequired
- citystringrequired
- countryCodestringrequired
- phonestring
- emailstring
- websitestring
- taxNumberstring
- vatIdstring
- smallBusinessbooleanrequired
- commercialRegisterobject
  - courtstring
  - numberstring
- bankobject
  - accountHolderstring
  - ibanstring
  - bicstring
  - bankNamestring
- invoiceFooterstring
issueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
serviceDatestring (date) | nullrequired
Date (YYYY-MM-DD)
servicePeriodServicePeriod | nullrequired
- fromstring (date)required
  Date (YYYY-MM-DD)
- tostring (date)required
  Date (YYYY-MM-DD)
serviceDateSource"entered" | "period" | "confirmed_issue_date" | "recurring" | "not_applicable" | nullrequired
Source of the date of supply (ST-13): confirmed_issue_date = confirmed by the user
issuanceInvoiceIssuance | nullrequired
Evidence of issue (from finalising, ST-14)
- finalizedAtstring (date-time)required
  Server time of finalising
- serverDatestring (date)required
  Calendar day of finalising (Europe/Berlin)
- issueDatestring (date)required
  Date (YYYY-MM-DD)
- issueDateSource"finalize_day" | "entered"required
  finalize_day = day of finalising, entered = entered in the draft
- deviationDaysintegerrequired
  Issue date minus finalising day in days (negative = earlier)
  -9007199254740991–9007199254740991
- reasonstring | nullrequired
  Reason for a differing issue date
- numberstring | nullrequired
- numberRangestringrequired
  Number range
dueDatestring (date) | nullrequired
Date (YYYY-MM-DD)
paymentTermsDaysintegerrequired
-9007199254740991–9007199254740991
priceMode"net" | "gross"required
taxTreatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
Tax treatment of the receipt
taxNoticestring | nullrequired
Mandatory notice (§ 19, § 13b, intra-Community supply …)
taxCaseInvoiceTaxCase | nullrequired
Tax case (tax assistant); saved at the latest when finalising
- factsobjectrequired
  - kind"goods" | "service" | "construction" | "property_service" | "electronic_service"required
    Type of supply
  - smallBusinessbooleanrequired
  - customerCountrystringrequired
    Country of residence of the recipient
    max. 2 characters
  - customerIsBusinessbooleanrequired
    Recipient is a business and receives the supply for its business
  - customerVatIdValidbooleanrequired
    a valid VAT ID of the recipient is available
  - destinationCountrystring | null
    Supply of goods: country of destination
    max. 2 characters
  - propertyCountrystring | null
    Service related to real estate: location of the property
    max. 2 characters
  - exemption"§ 4 Nr. 8 UStG" | "§ 4 Nr. 11 UStG" | "§ 4 Nr. 12 UStG" | "§ 4 Nr. 14 UStG" | "§ 4 Nr. 21 UStG" | "other" | null
    VAT exemption without input VAT deduction
- treatment"regular" | "small_business" | "reverse_charge" | "intra_eu_supply" | "export" | "non_taxable"required
  Tax treatment of the receipt
- placeOfSupplystringrequired
  Place of supply (ISO country)
- legalBasisstringrequired
- noticeVariantenum | nullrequired
  Case variant of the mandatory notice (ST-03)
  Values: small_business, reverse_charge, reverse_charge_eu, intra_eu_supply, export, non_taxable, tax_exempt
- ustvaKzstring | nullrequired
  Advance VAT return form field of the tax base (not for standard taxation)
- reportingArray<"ustva" | "zm" | "none">required
- confidence"certain" | "likely" | "review"required
- assumedbooleanrequired
  Facts assumed from the invoice data (not entered)
- reasonsArray<string>required
- warningsArray<string>required
currency"EUR"required
subjectstringrequired
introTextstringrequired
closingTextstringrequired
referencestringrequired
linesArray<DocumentLine>required
- idstring
  stable line item ID (assigned by the server if empty)
  max. 40 characters
- type"item" | "text" | "subtotal"
  Line item, plain text line or subtotal
  Default: "item"
- articleIdstring
  Reference to the article master data
  max. 128 characters
- titlestringrequired
  max. 300 characters
- descriptionstring
  max. 5000 characters
- quantitynumber
  -1000000–1000000 · Default: 1
- unitstring
  Unit, e.g. Stk, Std, pauschal (piece, hour, flat rate); UN/ECE Rec 20 for e-invoicing: module
  max. 20 characters
- unitPriceCentsinteger
  Amount in cents
  -100000000000–100000000000 · Default: 0
- discountPercentnumber
  0–100
- taxRatenumber
  Tax rate in per cent (19, 7, 0 …)
  0–100 · Default: 19
- totalCentsinteger
  Amount in cents
  -100000000000–100000000000
- servicePeriodobject
  - fromstring (date)required
    Date (YYYY-MM-DD)
  - tostring (date)required
    Date (YYYY-MM-DD)
- projectIdstring
  max. 128 characters
- timeEntryIdsArray<string>
  max. 128 characters
totalsDocumentTotalsrequired
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - categorystringrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - grossCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
deductionsArray<InvoiceDeduction>required
Final invoice: advance payments actually received and deducted (ST-09)
- invoiceIdstringrequired
  max. 128 characters
- numberstringrequired
- issueDatestring (date)required
  Date (YYYY-MM-DD)
- netCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- taxCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- grossCentsintegerrequired
  Amount in cents
  -100000000000–100000000000
- groupsArray<object>required
  - taxRatenumberrequired
  - netCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
  - taxCentsintegerrequired
    Amount in cents
    -100000000000–100000000000
- invoiceGrossCentsinteger
  Invoice amount of the progress invoice (ST-09)
  -100000000000–100000000000
- unpaidCentsinteger
  Unreceived remainder of the progress invoice – not deducted (ST-09)
  -100000000000–100000000000
amountDueCentsintegerrequired
Amount payable (gross less progress invoices)
-100000000000–100000000000
paidCentsintegerrequired
Amount in cents
-100000000000–100000000000
creditedCentsintegerrequired
reduced by invoice corrections (progress invoice: incl. the remainder settled with the final invoice)
-100000000000–100000000000
deductedCentsinteger | nullrequired
Progress invoice: amount received and deducted in the final invoice (ST-09)
-100000000000–100000000000
supersededCentsinteger | nullrequired
Progress invoice: unpaid remainder settled with the final invoice (ST-09)
-100000000000–100000000000
openCentsintegerrequired
Amount in cents
-100000000000–100000000000
relatedInvoiceIdstring | nullrequired
max. 128 characters
advanceInvoiceIdsArray<string>required
max. 128 characters
offerIdstring | nullrequired
max. 128 characters
projectIdstring | nullrequired
max. 128 characters
recurringInvoiceIdstring | nullrequired
max. 128 characters
canceledByInvoiceIdstring | nullrequired
Cancellation invoice for this invoice
max. 128 characters
debtIdstring | nullrequired
Debt in dunning (after handover)
max. 128 characters
showGiroCodebooleanrequired
einvoiceFormat"none" | "zugferd" | "xrechnung"required
language"de" | "en"required
Document language (fixed on finalisation)
dispatchobjectrequired
- countintegerrequired
  -9007199254740991–9007199254740991
- lastChannel"email" | "post" | nullrequired
- lastSentAtstring (date-time) | nullrequired
  Timestamp (ISO 8601)
pdfobject | nullrequired
archived PDF (after finalisation)
- sha256stringrequired
- createdAtstring (date-time)required
  Timestamp (ISO 8601)
lockedbooleanrequired
lockedAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
paidAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
handedOverAtstring (date-time) | nullrequired
Timestamp (ISO 8601)
createdAtstring (date-time)required
Timestamp (ISO 8601)
updatedAtstring (date-time)required
Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/recurring-invoices/ID/run' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Response 201

{
  "id": "string",
  "object": "invoice",
  "type": "invoice",
  "kind": "standard",
  "status": "draft",
  "number": "string",
  "contactId": "string",
  "recipient": {
    "name": "string",
    "addition": "string",
    "street": "",
    "zipCode": "",
    "city": "",
    "country": "DE",
    "email": "[email protected]",
    "vatId": "string",
    "leitwegId": "string",
    "einvoiceRecipientType": "business",
    "customerNumber": "string"
  },
  "sender": {
    "companyName": "string",
    "ownerName": "string",
    "legalForm": "string",
    "managingDirectors": "string",
    "street": "string",
    "zipCode": "string",
    "city": "string",
    "countryCode": "string",
    "phone": "string",
    "email": "string",
    "website": "string",
    "taxNumber": "string",
    "vatId": "string",
    "smallBusiness": false,
    "commercialRegister": {
      "court": "string",
      "number": "string"
    },
    "bank": {
      "accountHolder": "string",
      "iban": "string",
      "bic": "string",
      "bankName": "string"
    },
    "invoiceFooter": "string"
  },
  "issueDate": "2026-11-01",
  "serviceDate": "2026-11-01",
  "servicePeriod": {
    "from": "2026-11-01",
    "to": "2026-11-01"
  },
  "serviceDateSource": "entered",
  "issuance": {
    "finalizedAt": "2026-11-01T09:30:00.000Z",
    "serverDate": "2026-11-01",
    "issueDate": "2026-11-01",
    "issueDateSource": "finalize_day",
    "deviationDays": 0,
    "reason": "string",
    "number": "string",
    "numberRange": "string"
  },
  "dueDate": "2026-11-01",
  "paymentTermsDays": 0,
  "priceMode": "net",
  "taxTreatment": "regular",
  "taxNotice": "string",
  "taxCase": {
    "facts": {
      "kind": "goods",
      "smallBusiness": false,
      "customerCountry": "string",
      "customerIsBusiness": false,
      "customerVatIdValid": false,
      "destinationCountry": null,
      "propertyCountry": null,
      "exemption": null
    },
    "treatment": "regular",
    "placeOfSupply": "string",
    "legalBasis": "string",
    "noticeVariant": "small_business",
    "ustvaKz": "string",
    "reporting": [
      "ustva"
    ],
    "confidence": "certain",
    "assumed": false,
    "reasons": [
      "string"
    ],
    "warnings": [
      "string"
    ]
  },
  "currency": "EUR",
  "subject": "string",
  "introText": "string",
  "closingText": "string",
  "reference": "string",
  "lines": [
    {
      "id": "string",
      "type": "item",
      "articleId": "string",
      "title": "string",
      "description": "string",
      "quantity": 1,
      "unit": "string",
      "unitPriceCents": 0,
      "discountPercent": 0,
      "taxRate": 19,
      "totalCents": 0,
      "servicePeriod": {
        "from": "2026-11-01",
        "to": "2026-11-01"
      },
      "projectId": "string",
      "timeEntryIds": [
        "string"
      ]
    }
  ],
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0,
    "groups": [
      {
        "taxRate": 0,
        "category": "string",
        "netCents": 0,
        "taxCents": 0,
        "grossCents": 0
      }
    ]
  },
  "deductions": [
    {
      "invoiceId": "string",
      "number": "string",
      "issueDate": "2026-11-01",
      "netCents": 0,
      "taxCents": 0,
      "grossCents": 0,
      "groups": [
        {
          "taxRate": null,
          "netCents": null,
          "taxCents": null
        }
      ],
      "invoiceGrossCents": 0,
      "unpaidCents": 0
    }
  ],
  "amountDueCents": 0,
  "paidCents": 0,
  "creditedCents": 0,
  "deductedCents": 0,
  "supersededCents": 0,
  "openCents": 0,
  "relatedInvoiceId": "string",
  "advanceInvoiceIds": [
    "string"
  ],
  "offerId": "string",
  "projectId": "string",
  "recurringInvoiceId": "string",
  "canceledByInvoiceId": "string",
  "debtId": "string",
  "showGiroCode": false,
  "einvoiceFormat": "none",
  "language": "de",
  "dispatch": {
    "count": 0,
    "lastChannel": "email",
    "lastSentAt": "2026-11-01T09:30:00.000Z"
  },
  "pdf": {
    "sha256": "string",
    "createdAt": "2026-11-01T09:30:00.000Z"
  },
  "locked": false,
  "lockedAt": "2026-11-01T09:30:00.000Z",
  "paidAt": "2026-11-01T09:30:00.000Z",
  "handedOverAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}