Skip to main content

Request Invoices (Consolidated)

POST 
/api/suppliers/:supplier/request-invoices

Send a supplier one consolidated email requesting the outstanding invoices for several purchase orders at once. Each selected PO is re-validated server-side: it must belong to this supplier AND still be awaiting its invoice — ineligible ids are skipped and reported back (not emailed). Every PO that IS sent is stamped (invoice_requested_at, invoice_request_count++, invoice_last_requested_by).

Required scope: suppliers:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

If none of the selected POs are eligible, returns 422.

Authentication: Requires Bearer token. Requires permission: purchase_orders.update. Throttled: 60 requests/min.

Body fields:

  • to (string, required) — recipient email
  • subject (string, required, max 255)
  • purchase_order_ids (array of ints, required, min 1) — POs to include
  • note (string, optional, max 2000)
  • cc (array of emails, optional, max 10)

Requires both the suppliers and purchase-orders token scopes (it mutates purchase orders by stamping invoice-request tracking), plus the purchase_orders.update permission.

Delivery outcome: the request email is sent from a background job, so a successful response means the request was queued and stamped, not that the supplier has received it. If the email later fails for good (rejected recipient, mail relay refusal, missing attachment), each purchase order in the email reports it: invoice_request_failed_at (ISO 8601) and invoice_request_error (the transport's reason, up to 500 characters). Both are null while nothing is known to have failed, and both are cleared the moment a new request is queued — they always describe the latest request. invoice_requested_at and invoice_request_count are not rolled back by a failure.

Request​

Responses​

OK

Response Headers
    Content-Type