Skip to main content

Request Invoice (Single PO)

POST 
/api/purchase-orders/:purchase_order/request-invoice

Email the supplier requesting the outstanding invoice for a single purchase order, optionally attaching vendor-deposit documents (e.g. proof of the prepayment). The reply-to is set to the sending user. On success the PO is stamped: invoice_requested_at = now, invoice_request_count incremented, invoice_last_requested_by = current user.

Required scope: purchase-orders:write

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

Only allowed when the PO is still awaiting its invoice (invoice_status in uninvoiced/partially_invoiced AND submission_status in submitted/finalized) — otherwise 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)
  • note (string, optional, max 2000) — appended to the email body
  • cc (array of emails, optional, max 10)
  • attachment_ids (array of ints, optional) — VendorDepositAttachment ids; each MUST belong to one of this PO's deposits or the request is rejected (422)

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), the purchase order 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