Record a payment on a sales invoice

Records a customer payment against an approved sales invoice: payment_account_transaction_id applies an incoming bank line (its whole amount), or payment_account_id, amount and payment_date record a manual payment. A payment short of what is open leaves the rest open, unless shortfall_reason closes it in the same journal entry, with no VAT: withholding_tax is tax the customer withheld at source and paid to its tax authority (a German § 50a withholding, for example), posted to shortfall_account_id, which must be a postable asset under Other current assets (a withholding tax receivable, refundable under a treaty) or an income tax expense account; fee, bad_debt and other (with a description) post to an expense. The journal is Dr bank (what arrived) + Dr the shortfall account (the rest) / Cr Accounts Receivable (what was open), and the invoice is paid in full. The amount closed is always derived by the server (open less what the payment settles), never sent. A shortfall needs write_off_receivables (without it a withholding is refused with write_off_not_permitted, the other reasons with 403); a withholding may not exceed half of the invoice's gross. Refusals name their code: write_off_not_permitted, withholding_tax_account_required, withholding_tax_account_unavailable, withholding_tax_currency_mismatch, withholding_tax_nothing_withheld, withholding_tax_exceeds_limit. The response's shortfall names what closed the rest. When the tax authority later refunds a withholding, categorize that bank receipt to the same receivable account. Preview first with invoice.allocatePaymentPreview and send its ETag as If-Match. Requires Idempotency-Key, If-Match, the invoices:action OAuth scope with update_invoices and update_bank_accounts.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required
Body Params

Fields accepted to record a payment on a sales invoice. The schema identifies required and optional values.

string | null
string
number
number

Not accepted.

date
string | null

Required for other (what the rest was); for withholding_tax, the tax withheld.

string | null
enum

A short payment: leave_open (default) keeps the rest open;
withholding_tax posts it to shortfall_account_id; fee,
bad_debt and other write it off. These need
write_off_receivables, settle in full and carry no VAT.
discount is refused.

Allowed:
integer | null

Chart-of-accounts id the rest posts to; required for withholding_tax and other.

string

Not accepted: the payment-date rate applies.

Headers
string
required
length ≤ 191

Required unique key whose request hash and terminal response are stored durably for 24 hours.

string

Required. ETag from the latest representation; a stale value returns 412 precondition_failed. Send this header, not the standard If-Match: some HTTP intermediaries evaluate a standard If-Match themselves and can answer 412 even though the change was applied. Never send both; both with different ETags returns 400 conflicting_precondition_headers.

string
deprecated

Accepted with the same value and meaning as Cybooks-If-Match, but do not send it: an intermediary can answer 412 to it after the change was applied. Send Cybooks-If-Match instead.

Responses

Language
Credentials
OAuth2
Missing 1 required scope
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json
*/*