Apply a standalone payment

Operation ID: applyStandalonePayment

Group: Accounting › Standalone Payments

Open in the interactive reference

POST /accounting/standalone-payments/apply

Retry-safe: A write that accepts Idempotency-Key: repeating a request with the same key replays the stored answer instead of executing twice.

Applies a standalone payment to bills, expense reports, or tax entries. Each line is one application: an outbound payment to a vendor bill, expense report, or withholding tax entry. If any line fails a check, nothing is applied.

Only a standalone payment can be applied: one created with POST accounting/outbound-payments whose lines name no source document. A payment created against a source document is already linked to that document and is refused.

On each line, the payment and the document must have the same business partner and currency, and the same offset account when both have one. The document must have an open balance, and a vendor bill or expense report must be approved. A voided vendor bill is refused. An expense report must be reimbursable, unless it is an employee advance. A withholding tax entry needs a payment that has an offset account. Each payment and document pair can appear only once in a request.

The amount must be above zero. The amount can't be more than the payment's unapplied amount or the document's open balance, counting earlier lines in the same request.

appliedDate can't be earlier than the payment date. The accounting period must be open on that date for the legal entities of both the payment and the document.

Applying to a vendor bill also records any realized foreign exchange gain or loss in a journal entry. Applying to an expense report or a withholding tax entry does not.

Parameters

Name In Type Required Description
Api-Version header string · v1 yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.
Idempotency-Key header string no An opaque caller-chosen string (1-255 characters) that makes this request safe to retry. Repeating the same key with an identical request body replays the original response instead of re-executing - but only once that original request succeeded; a failed attempt re-executes on retry. Repeating the key with a different body is answered with 422. A key still in flight is answered with 409 - as is a key whose original request was interrupted before it finished, for a few minutes afterwards, until that attempt is presumed dead. A completed response stays replayable for 24 hours. The key is scoped to the caller, not to the action: reusing it for a different action is answered with 409 or 422 rather than treated independently. On read actions this header is ignored. On write actions that cannot offer the guarantee it is answered with 400 IDEMPOTENCY_NOT_SUPPORTED rather than silently ignored.

Request body

Required, application/json: applyStandalonePaymentInput.

Field Type Required Description
lines array<object> yes One or more application lines. All-or-nothing: the whole batch is rejected if any line fails a check. Example: [{"outboundPaymentId":"c91f4a22-6d90-4c53-8e17-9f2a4b6c8d06","appliedDocumentType":"VendorBillHeaderBase","appliedDocumentId":"d02f4a22-6d90-4c53-8e17-9f2a4b6c8d07","amount":"500.00"}].
lines[].outboundPaymentId string yes Id (a UUID) of the standalone outbound payment being applied.
lines[].appliedDocumentType string yes Kind of document this line settles: 'VendorBillHeaderBase', 'ExpenseReportBase' or 'WithholdingTaxEntry'.
lines[].appliedDocumentId string yes Id (a UUID) of the target document.
lines[].amount decimal yes Amount applied, in the payment's currency. Must be greater than zero and not exceed the lesser of the payment's remaining unapplied amount and the document's open balance.
lines[].appliedDate date no Date of application. Must not precede the payment's own date. Omit to default to the payment's date. 
{
  "lines": [
    {
      "outboundPaymentId": "c91f4a22-6d90-4c53-8e17-9f2a4b6c8d06",
      "appliedDocumentType": "VendorBillHeaderBase",
      "appliedDocumentId": "d02f4a22-6d90-4c53-8e17-9f2a4b6c8d07",
      "amount": "500.00"
    }
  ]
}

Response

200 Success

Under data (applyStandalonePaymentOutput):

Field Type Required Description
applications array<object> yes The created applications, one per input line, in the same order.
applications[].id string yes Id (a UUID) of the created application.
applications[].outboundPaymentId string yes Id (a UUID) of the outbound payment this application belongs to.
applications[].appliedDocumentType string yes Kind of document settled.
applications[].appliedDocumentId string yes Id of the settled document.
applications[].amount object yes Amount applied.
applications[].amount.amount string yes
applications[].amount.currency string yes
applications[].appliedDate date yes Date of application. 
{
  "data": {
    "applications": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "outboundPaymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "appliedDocumentType": "<appliedDocumentType>",
        "appliedDocumentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "amount": {
          "amount": "<amount>",
          "currency": "<currency>"
        },
        "appliedDate": "2026-01-15"
      }
    ]
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Response headers

Errors

Code Status
EMPTY_BATCH 400
PAYMENT_NOT_FOUND 400
DOCUMENT_NOT_FOUND 400
APPLICATION_REJECTED 400
IDEMPOTENCY_KEY_CONFLICT 409
IDEMPOTENCY_PAYLOAD_MISMATCH 422

Statuses