# Invoice and Receipt API

> Query and download order invoice and receipt documents.

Canonical: https://stafiel.org/documentation/developer-integration/invoice-and-receipt-api
Version: v1.0.0

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-2026-0001",
        "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"
        }
      },
      "receipt": {
        "type": "receipt",
        "status": "ready",
        "documentNumber": "RCT-2026-0001",
        "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"
        }
      }
    }
  }
}

### 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.contentType
string
PDF content type when available.

pdf.downloadUrl
string
Authenticated PDF download URL when available.

## 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: inline; filename="invoice-ord_your_order_id.pdf"

## 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
PDF is not available or the document is voided.

429
RATE_LIMIT_EXCEEDED
Too many requests. Retry after the indicated time.