Advance payments and payment date validation

30 October 2026 — The date of a payment no longer has to be on or after the issue date of the document. A payment made before the document was issued is an advance payment and is accepted. A payment date later than today is rejected with a 422 domain error.

Operations in this release

The rule

A payment date must not be later than today (Europe/Madrid day). Nothing else limits it.

• Before the issue date: accepted. A customer can pay before the invoice is issued, and you can pay a supplier before its document arrives. Record the real date: it is the one used by the collection cycle, the aging reports and the bank reconciliation. Do not alter the date to fit the issue date.
• Later than today: 422. Registering a payment confirms something that already happened. A payment that is only expected is the due date of the document.

The response is 422. The error always points at the date, but its code, subcode and param depend on the operation:

• Sales, mark-paid and payments: error.code business_rule_violation, no error.subcode, error.param payment_date.
• Expenses, mark-paid: error.code invalid_payment_date, no error.subcode, error.param payment_date.
• Expenses, payments: error.code business_rule_violation, error.subcode invalid_payment_date, error.param paid_on.

On three of the four operations param carries the name the date has in the domain (payment_date), even though the request field is paid_on. To tell this error from other 422 responses, check these values for the operation you called. Do not match on message.

What was wrong before

• A paid_on earlier than the issue date was rejected, so an advance payment could not be recorded with its real date.
• POST /v1/companies/{company}/invoices/{invoice}/mark-paid with a future paid_on answered 500. It now answers the same 422 as the other operations.

Same rule everywhere

• Bulk status. POST /v1/companies/{company}/invoices/bulk-status and POST /v1/companies/{company}/purchase-invoices/bulk-status take the date in payment_date and apply the same rule. A payment_date later than today rejects the whole call with 422 (error.code invalid_param_value, param payment_date) before any document is processed. A date before the issue date of a document is accepted. failures[] reports only the documents that cannot take the payment for another reason, such as an unknown id or a status that does not allow it.
• MCP. The four tools above follow the same rule and answer with the same error as their REST operation.
• Payment gateways. Stripe collections on an existing invoice are recorded with the real date of the charge, never later than today. They are no longer moved forward to the issue date of the invoice.

What to do:

1. Send the real date of the payment in paid_on, even when it is earlier than the issue date.
2. Do not send a future date. If you handled the old 500 of mark-paid, handle the 422 instead.
3. Do not rely on paid_on being on or after issued_on in your own validations or reports.

The table below lists the operations of this release.