Invoice Payment

Invoice payments represent incoming payments received from customers to settle invoices. They track payment details including payment type, bank accounts, execution dates, and amounts. The system automatically handles overpayments by creating customer debit entries and supports various payment types including customer payments, debits, and credits.

• Create an invoice payment
• Cancel an invoice
• Retrieve an invoice payment
• Delete an invoice payment
• List invoice payments
• Payment Types and Behavior
  • Payment Types
  • Automatic Processing
  • Customer Account Integration

Create an invoice payment

post

/invoice/{invoice_id}/payment

Attribute (* required)	Type	Description
type	String?	Payment type: customer_payment, customer_debit, customer_credit, cash_discount, credit_note, receivables_loss, cancellation (defaults to customer_payment)
bank_account_id	String?	ID of one of your bank accounts (defaults to the invoice bank account)
amount *	Float	Payment amount (at least 0.01). Not used for cancellation, see Cancel an invoice
currency	String?	ISO 4217 currency code (defaults to the invoice currency)
conversion_rate	Float?	Exchange rate to the base currency, at least 0.0001 (defaults to the rate of the latest payment or the invoice)
message	String?	Payment description or reference (max. 255 characters)
executed_at	Date?	Payment execution date (defaults to current date)

Overpayment Handling

When the payment amount exceeds the invoice's open amount, the system automatically:

1. Creates a payment for the exact open amount
2. Creates a separate customer debit entry for the excess amount

Example response

// HTTP 201 Created
{
    "id": "v7rnRjBn9o",
    "type": "customer_payment",
    "invoice_id": "AG52olvLXP",
    "invoice": null,
    "bank_account": null,
    "amount": 1250.00,
    "message": "Bank transfer payment",
    "executed_at": "2024-01-15"
}

Cancel an invoice

post

/invoice/{invoice_id}/payment

A payment of type cancellation cancels the open amount of a sent invoice. The invoice and its number stay; the cancellation reverses the open amount in the books on executed_at. Customers are not notified.

Attribute (* required)	Type	Description
type *	String	cancellation
executed_at	Date?	Cancellation date, on or after the invoice's issued_at (defaults to current date)
description	String?	Reason for the cancellation

The amount is always the invoice's current total_open; an amount in the request is ignored. Payments and other reductions already recorded (such as cash_discount or credit_note) are kept.

• Without any customer_payment, customer_debit or customer_credit, the invoice is fully cancelled: it gets status cancelled (is_cancelled: true, is_paid: false, cancelled_at set to executed_at) and sends the invoice/cancelled webhook event. Its PDF shows a cancellation stamp and no QR-bill.
• With one of these payments, only the remaining open amount is cancelled: the invoice gets status paid, keeps is_cancelled: false and sends invoice/paid.

An invoice only counts as cancelled while it is fully settled. If a payment is deleted after a remainder cancellation, for example the customer_payment, the invoice is open again and keeps is_cancelled: false.

The request returns 422 Unprocessable Entity when the invoice is not locked, has no open amount, executed_at is before issued_at, or executed_at falls in a closed fiscal year.

To reactivate a cancelled invoice, delete the cancellation payment. This returns 422 when its executed_at falls in a closed fiscal year.

Example request

{
    "type": "cancellation",
    "executed_at": "2026-10-23",
    "description": "Wrong recipient"
}

Example response

// HTTP 201 Created
{
    "id": "x8tnRjBn9o",
    "type": "cancellation",
    "invoice_id": "AG52olvLXP",
    "invoice": null,
    "bank_account": null,
    "amount": 1250.00,
    "message": "Wrong recipient",
    "executed_at": "2026-10-23"
}

Retrieve an invoice payment

get

/invoice/{invoice_id}/payment/{id}

Example response

// HTTP 200 OK
{
    "id": "v7rnRjBn9o",
    "type": "customer_payment",
    "invoice_id": "AG52olvLXP",
    "invoice": {
        "id": "AG52olvLXP",
        "number": "R-2024-0001",
        "name": "Website Development",
        "total": 1250.00,
        "total_paid": 1250.00,
        "total_open": 0
    },
    "bank_account": {
        "id": "bk1nRjBn9o",
        "name": "UBS Business Account",
        "currency": "CHF",
        "iban": "CH9300762011623852957"
    },
    "amount": 1250.00,
    "message": "Bank transfer payment - Invoice R-2024-0001",
    "executed_at": "2024-01-15"
}

Delete an invoice payment

delete

/invoice/{invoice_id}/payment/{id}

Deleting a cancellation payment reactivates the invoice. It returns 422 Unprocessable Entity when the payment's executed_at falls in a closed fiscal year.

Example response

// HTTP 204 No Content

List invoice payments

get

/invoice/{invoice_id}/payment

The list endpoint accepts the same parameters as in Retrieve an invoice payment and returns a paginated array of the same invoice payment object in the data property.

Read more about Pagination, Filtering, Sorting and Includes on the Introduction page.

Payment Types and Behavior

Payment Types

• customer_payment: Standard incoming payment from customer (default)
• customer_debit: Debit entry in customer account (e.g., from overpayments)
• customer_credit: Credit entry in customer account (e.g., refunds, adjustments)
• cash_discount: Cash discount applied to invoice (early payment discount)
• credit_note: Credit note applied against invoice
• receivables_loss: Write-off of uncollectable receivable
• cancellation: Cancellation of the open amount of an invalid invoice (see Cancel an invoice)

Automatic Processing

When an invoice payment is created, the system automatically:

1. Validates amount: Prevents payments with zero or negative amounts
2. Sets defaults: Assigns default bank account and payment type if not specified
3. Handles overpayments: Splits overpayments into payment + customer debit
4. Updates invoice: Recalculates total_paid and marks invoice as paid when fully settled
5. Creates customer transactions: For debit/credit payments, creates corresponding customer account entries
6. Logs activity: Records payment creation/deletion in the invoice activity log

Customer Account Integration

Customer debit and credit payments automatically create entries in the customer's account ledger, allowing for:

• Account balance tracking
• Credit/debit management
• Payment reconciliation across multiple invoices

When a payment is deleted, any associated customer transaction is also removed to maintain data consistency.