Update Invoice Status

PATCH/invoices/{id}/status

Summary

Updates a non-draft invoice belonging to a company accessible to the key. Requires write:invoices. The id can be the invoice ID or nanoid.

Request Body

Field	Type	Required	Description
status	string	Yes	unpaid, posted, or paid
paymentDate	string	When paid	Valid date in YYYY-MM-DD format; only for paid
ref	string	When paid	Non-blank payment reference; only for paid
comments	string	No	Payment comments; only for paid
file	object	No	Optional payment attachment; only for paid Show child attributes uploadToken (string, conditional): token from Create File Upload; use this after uploading the file fileName (string, conditional): original filename; required for inline uploads content (string, conditional): complete PDF, JPEG, or PNG base64 data URL; required for inline uploads

When marking an invoice paid, reference and date are required, including on repeated paid requests. Comments and attachment are optional. Follow the shared File Uploads steps. Request an upload link and submit file: { "uploadToken": "<TOKEN>" }. Requidex verifies the uploaded bytes before attaching them. Inline base64 uploads remain supported. Do not combine the two formats or supply a storage key or URL. The maximum decoded size is 20 MB per file and the complete JSON request must fit within 50 MB. Payment fields and attachments are rejected for unpaid and posted.

• unpaid sets the stored status to pending, clears payment and confirmation details, and clears posting to finance
• posted sets the stored status to pending and records posting to finance; any previous payment and confirmation details are cleared
• paid sets the stored status to confirmed, records payment and confirmation details, and marks the invoice posted to finance

Repeating the current state succeeds without recording another activity or status webhook. A repeated paid request does not update existing payment details or attachments. Changes are recorded in invoice activity. Newly marking an invoice paid emits invoice_paid; explicitly setting it to posted emits invoice_posted. Marking paid does not also emit invoice_posted. Events are delivered to eligible subscriptions.

Include file content in a request

You can also include the payment attachment directly in the file field instead of requesting an upload link:

{
  "fileName": "remittance.pdf",
  "content": "data:application/pdf;base64,<BASE64_FILE_CONTENT>"
}

Replace the placeholder with the base64-encoded bytes of the complete file. Include the MIME type and ;base64, prefix. PDF, JPEG, and PNG files are supported, up to 20 MB per decoded file. Do not combine uploadToken with fileName or content. Base64 encoding increases the request size, so the complete JSON request must fit within 50 MB. The attachment remains optional and is only accepted when marking the invoice paid.

Request Example

curl -X PATCH 'https://api.requidex.com/api/open/v1/invoices/{id}/status' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"status":"paid","paymentDate":"2026-10-12","ref":"PAY-123","comments":"Bank transfer","file":{"uploadToken":"<UPLOAD_TOKEN>"}}'

Response

Returns the updated invoice in the same success envelope and field format as Get Invoice. A key does not need read:invoices to receive this response.

Errors

HTTP status	Description
400	Invalid status, payment details, unknown fields, or unsupported current invoice status
401	Missing or invalid authentication
403	Missing write:invoices or hiring company has not enabled the agency action
404	Invoice not found, outside the selected company scope, draft, or AfP
429	Rate limit exceeded
500	Invoice update failed