Invoice and Receipt API

Query and download order invoice and receipt documents.

Use the Invoice and Receipt API to query document status and download generated PDFs for an order.

Get Documents

Endpoint

GET /api/v1/orders/{orderId}/documents

Parameters

Field	Required	Default	Description
`orderId`	Yes	None	Path parameter. Stafiel order ID.
`merchantId`	Yes	None	Query parameter. Merchant ID bound to the API key.

Request Example

curl "https://api.stafiel.com/api/v1/orders/ord_your_order_id/documents?merchantId=mch_your_merchant_id" \
  -H "X-API-Key: mk_live_your_api_key" \
  -H "X-App-Client: merchant-client"

Success Response

{
  "success": true,
  "data": {
    "orderId": "ord_your_order_id",
    "documents": {
      "invoice": {
        "type": "invoice",
        "status": "ready",
        "documentNumber": "Inv-20260519-ABC1234567",
        "issuedAt": "2026-05-19T12:00:00.000Z",
        "canDownloadPdf": true,
        "pdf": {
          "contentType": "application/pdf",
          "downloadUrl": "https://api.stafiel.com/api/v1/orders/ord_your_order_id/documents/invoice/pdf?merchantId=mch_your_merchant_id"
        },
        "snapshot": {}
      },
      "receipt": {
        "type": "receipt",
        "status": "ready",
        "documentNumber": "Rct-20260519-ABC1234567",
        "issuedAt": "2026-05-19T12:05:00.000Z",
        "canDownloadPdf": true,
        "pdf": {
          "contentType": "application/pdf",
          "downloadUrl": "https://api.stafiel.com/api/v1/orders/ord_your_order_id/documents/receipt/pdf?merchantId=mch_your_merchant_id"
        },
        "snapshot": {}
      }
    }
  }
}

Response Fields

Field	Type	Description
`orderId`	string	Stafiel order ID.
`documents`	object	Document objects keyed by `invoice` and `receipt`.
`type`	string	Document type, either `invoice` or `receipt`.
`status`	string or null	Document generation status.
`documentNumber`	string or null	Generated invoice or receipt number.
`issuedAt`	string or null	ISO 8601 issue timestamp.
`canDownloadPdf`	boolean	Whether the PDF is currently available for download.
`pdf`	object or null	Authenticated PDF download metadata when currently available.
`pdf.contentType`	string	PDF content type when available.
`pdf.downloadUrl`	string	Authenticated PDF download URL when available.
`snapshot`	object or null	Public document snapshot when available.

Each invoice and receipt object contains exactly type, status, documentNumber, issuedAt, canDownloadPdf, pdf, and snapshot. Use canDownloadPdf as the API signal before requesting the PDF. The download endpoint returns the final request outcome.

Download PDF

Endpoint

GET /api/v1/orders/{orderId}/documents/invoice/pdf
GET /api/v1/orders/{orderId}/documents/receipt/pdf

Parameters

Field	Required	Default	Description
`orderId`	Yes	None	Path parameter. Stafiel order ID.
`documentType`	Yes	None	Path value. Use `invoice` or `receipt`.
`merchantId`	Yes	None	Query parameter. Merchant ID bound to the API key.

Request Example

curl "https://api.stafiel.com/api/v1/orders/ord_your_order_id/documents/invoice/pdf?merchantId=mch_your_merchant_id" \
  -H "X-API-Key: mk_live_your_api_key" \
  -H "X-App-Client: merchant-client"

Success Response

The PDF download endpoint does not return the standard JSON envelope.

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="Invoice-20260519-ABC1234567.pdf"; filename*=UTF-8''Invoice-20260519-ABC1234567.pdf
Cache-Control: private, no-store, max-age=0

Document Status

Document status may be queued, generating, ready, failed, voided, or null. A document becoming ready is not the source of truth for payment completion. Use order status and payment records for payment state.

Error Responses

HTTP Status	Code	Meaning
`400`	`VALIDATION_ERROR`	Query parameter is invalid or document type is unsupported.
`401`	`AUTH_FAILED`	API key is missing, invalid, or cannot access the requested merchant or order.
`403`	`AUTHORIZATION_ERROR`	Request is authenticated but not allowed.
`404`	`NOT_FOUND`	Order or document does not exist or is not visible.
`409`	`ORDER_DOCUMENT_NOT_READY` / `ORDER_DOCUMENT_VOIDED` / `ORDER_DOCUMENT_UNAVAILABLE`	PDF is not ready, is voided, or is currently unavailable.
`410`	`ORDER_DOCUMENT_EXPIRED`	The document retention period has expired.
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests. Retry after the indicated time.