Skip to navigation

Mark a proforma as paid

View as Markdown

Records one payment for the proforma. Without amount it settles the outstanding balance and payment_status derives to paid; with amount it records a partial payment and payment_status derives to partially_paid while a balance remains, through the same Transaction + allocation path the web “Record payment” flow uses.

The lifecycle status is not changed by the payment. A proforma moves to settled only once a final invoice derives from it (see convertProformaToInvoice), not when the money arrives.

paid_on defaults to today in the workspace’s time_zone. bank_account_id is optional; the proforma’s own account is used when set, otherwise the workspace’s cash register.

A retry after settlement returns 422 and does not record another payment.

Required scope: manage:proformas.

Authentication

AuthorizationBearer

JWT issued via POST /api/v1/auth/sign_in. Used by mobile and SPA clients. Revoked tokens are rejected.

OR
AuthorizationBearer

Lucanto API key. Two prefixes:

  • lct_pat_<random><checksum> — personal access token (owner: User)
  • lct_live_<random><checksum> — workspace token, live data

Issue keys at /settings/api_keys (personal) or /:workspace_id/settings/api_keys (workspace). Plaintext token is shown once and never again.

Path parameters

workspace_idlongRequired>=1
Workspace ID. The numeric ID shown in your URLs.
idlong or stringRequired

Proforma ID. Either the numeric id or the public_id (doc_…).

Headers

Idempotency-KeystringOptional<=255 characters

Client-supplied unique key (recommended: UUID v4) for safe retries. Within 24 hours, repeating the same key with the same request (method, path, query, body) replays the original response instead of re-executing the action — once the action has run, a 5xx included; a request stopped before it ran is not stored. Reusing a key with a different request returns 422 idempotency_key_conflict (IETF draft §2.7).

Request

This endpoint expects an object.
paid_ondateOptional
Payment date. Defaults to today when omitted.
amountstring or nullOptionalformat: "^\d+(\.\d{1,2})?$"

Payment amount in the proforma currency. Omit — or send an explicit null, which the API reads the same way — to settle the whole outstanding balance. A smaller amount records a partial payment: payment_status becomes partially_paid and amount_due drops by this amount; call again for the next instalment. An amount above the outstanding balance is accepted and recorded in full; payment_status then derives to overpaid.

bank_account_idlong or stringOptional

Workspace bank account (or cash register) to record the payment against. Must belong to this workspace — a foreign id is a 422, never a silent fallback.

Response

OK. The proforma with payment_status derived from the recorded payment (paid, partially_paid while a balance remains, or overpaid when the payment exceeds it); lifecycle status is unchanged.

idlong
public_idstringRead-onlyformat: "^[a-z]+_[0-7][0-9a-hjkmnp-tv-z]{25}$"

Stable public identifier of this record. Never changes once assigned. Its prefix names the entity: doc_ document (invoice, proforma, credit note, quote, sales order), exp_ expense, cnt_ contact, prj_ project, ba_ bank account or cash register, txn_ transaction, lon_ loan, bst_ bank statement. Accepted in place of the numeric id in this resource’s path parameters and in request fields that reference it (customer_id, bank_account_id, …).

typeenum
Allowed values:
statusenum

Proforma lifecycle state. Settlement degree is reported separately by payment_status; settled is the explicit lifecycle state after downstream settlement handling. reopened is where reopenProforma lands a previously locked proforma; it is editable again and must be re-issued.

currencystring
created_atdatetime
updated_atdatetime
payment_statusenum or nullOptional

Derived settlement degree (money is the source of truth). Null for non-payable document types, drafts, canceled documents, and rows created before the payment_status backfill ran.

Allowed values:
overdueboolean or nullOptional
Whether a positive balance remains after the due date.
paid_lateboolean or nullOptional
Whether full settlement landed after the due date.
status_transitionsobjectOptional
numberstring or nullOptional
issue_datedate or nullOptional
delivery_datedate or nullOptional
due_datedate or nullOptional
due_daysinteger or nullOptional
exchange_ratestring or nullOptionalformat: "decimal"
order_numberstring or nullOptional
included_in_turnoverboolean or nullOptional
reverse_chargeboolean or nullOptional
reverse_charge_textstring or nullOptional
tax_schemestringOptional

Tax scheme (UNCL 5153), e.g. “VAT”.

discount_descriptionstring or nullOptional
discount_percentagestring or nullOptionalformat: "decimal"
discount_amountstring or nullOptionalformat: "decimal"
opening_textstring or nullOptional
closing_textstring or nullOptional
footer_notestring or nullOptional
internal_notestring or nullOptional
pdf_languagestring or nullOptional
pdf_localestring or nullOptional
delivery_methodstring or nullOptional

Delivery/carrier mode

email_sent_atdatetime or nullOptional
auto_on_paymentstring or nullOptional

What happens when a payment lands on this proforma: regular_invoice_paid (delivered at payment: one paid invoice for a payment that covers it, a tax document for a part-payment), tax_document (a tax document for every payment), nothing, or the legacy regular_invoice. NULL on older proformas, read as nothing. When converting via /convert_to_invoice, this value is overridden to regular_invoice regardless of the stored setting.

amount_paidstring or nullOptionalformat: "decimal"

Amount settled so far (payments + advance deductions).

amount_duestring or nullOptionalformat: "decimal"

Outstanding amount (tax_inclusive − amount_paid).

paymentobjectOptional
import_sourceenum or nullOptional

Origin of the document. null when it was created in Lucanto, in which case totals are Lucanto’s EN 16931 calculation. A non-null value means the document was imported from that system and initially carries the source system’s own figures, preserved verbatim; those may differ by cents from Lucanto’s calculation because systems round VAT at different levels (line vs. category). insight means AI extraction from an uploaded file, not an import from another vendor. This records provenance only, not which calculation is currently in effect — editing line items or document discounts recomputes totals in Lucanto while leaving import_source set. In practice a document only ever carries kros_developer, isdoc, superfaktura or null. kros appears only on rows imported before the writer was renamed, and insight is written by the expense path only. The enum is kept as the union across resources rather than narrowed, so a legacy row cannot fail validation.

Allowed values:
totalsobjectOptional
settingsobjectOptional
line_itemslist of objectsOptional
customerobject or nullOptional

The party identity as it appears on a document. On an ISSUED document this is the identity the document was issued with — a snapshot pinned at issue, which does NOT change when the legal entity is later renamed, re-registered, or moved. A draft follows the entity’s current identity. id is the legal entity’s id and is stable across identity changes, so a stored reference keeps resolving. This matches the PDF and the ISDOC export of the same document. vat_period is not part of this projection — a counterparty’s filing period is not knowable.

supplierobject or nullOptional

The party identity as it appears on a document. On an ISSUED document this is the identity the document was issued with — a snapshot pinned at issue, which does NOT change when the legal entity is later renamed, re-registered, or moved. A draft follows the entity’s current identity. id is the legal entity’s id and is stable across identity changes, so a stored reference keeps resolving. This matches the PDF and the ISDOC export of the same document. vat_period is not part of this projection — a counterparty’s filing period is not knowable.

Errors

401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error