`POST /customers/orders/:id/documents`

Submit the supporting document a payment is waiting for. Some payments are held until a supporting document is reviewed, for example a payout over swift to a beneficiary other than the customer. A held order reads status: "under_review", and its status_reason follows the review:

`status_reason`	Meaning
`documents_required`	The payment is waiting for a supporting document. Submit one with this endpoint.
`documents_under_review`	A document was submitted and is under review.
`documents_rejected`	The submitted document was turned down. Submit another with this endpoint.
`documents_approved`	The review passed and the payment continues: `status` moves back to `processing`.

Each change of status_reason after you submit fires an order.status_changed webhook carrying the updated order, even while status stays under_review. The review only moves forward, so a late notice of an earlier stage never moves the order back.

Attaching a document in the accept body's files submits it with the order, so most payments never wait. Check the quote's acceptance_requirements.files_required before accepting. Use this endpoint when the order still asks for one: no document was attached, it was turned down, or the payment was funded through a deposit address after the accept, which carries no files.

The order moves to documents_under_review as the document is filed, and the response shows it. A retried or concurrent call then answers 409 OrderNotAwaitingDocuments instead of filing a second copy. If the filing fails, the order goes back to the reason it had and the call can be retried. The document is filed under the order's reference when it has one (an invoice number, typically), otherwise under its idempotency_key. The call is scoped to the org bound to the credential.

Request body

{
  "type": "invoice",
  "file": "data:application/pdf;base64,JVBERi0xLjcK…"
}

Field	Type	Notes
`type`	enum	What the document is, one of the supporting document types. Compliance review reads the document as this type. Optional for now, but required from November 1, 2026: send it on every submission.
`file`	string	Required. The document as a base64 data URI: `data:<mime>;base64,<contents>`. PDF / JPEG / PNG, at most 5 MB. It must show the relationship between the customer and the beneficiary, such as an invoice, contract, or purchase order.

Response `200`

The order, now reading status_reason: documents_under_review, same shape returned by POST /quotes/:id/accept. Watch for the webhook as the review moves on.

Errors

400 InvalidRequest: file is not a PDF, JPEG, or PNG base64 data URI, does not decode, is empty, or exceeds 5 MB.
422 InvalidRequest: type is not one of the supporting document types.
404 NotFound: no order with that id under your org.
409 OrderNotAwaitingDocuments: the order is not waiting for a supporting document. Its status_reason is neither documents_required nor documents_rejected, including because this document was already filed.

Example

curl -X POST "$SEISMIC_ORCHESTRATION_URL/v0/customers/orders/f01e…/documents" \
  -H "Api-Key: $SEISMIC_ORCHESTRATION_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"type\": \"invoice\",
    \"file\": \"data:application/pdf;base64,$(base64 -w0 invoice.pdf)\"
  }"

TypeScript

const order = await client.customers.submitOrderDocument(orderId, {
  type: "invoice",
  file,
});

POST /customers/orders/:id/documents