# Orders API

> Query order lists and order details through the API.

Canonical: https://stafiel.org/documentation/developer-integration/orders-api
Version: v1.0.0

Use the Orders API to list orders and retrieve a single order's current business
state.

## List Orders

### Endpoint

GET /api/v1/orders

### Query Parameters

Field
Required
Default
Description

merchantId
Yes
None
Merchant ID bound to the API key.

page
No
1
Page number. Starts from 1.

pageSize
No
20
Number of orders per page. Maximum 100.

status
No
None
Comma-separated order statuses, such as awaiting_payment, underpaid, fullpaid, overpaid, expired, settled, full_refunded, closed, or compliance_hold.

chainName
No
None
Comma-separated chain labels.

orderId
No
None
Search by Stafiel order ID or merchant business order reference.

contractAddress
No
None
Filter by payment contract or payment address.

createdAtFrom
No
None
ISO 8601 lower bound for order creation time.

createdAtTo
No
None
ISO 8601 upper bound for order creation time.

sortBy
No
createdAt
Use createdAt, status, or amount.

sortOrder
No
desc
Use asc or desc.

### Request Example

curl "https://api.stafiel.com/api/v1/orders?merchantId=mch_your_merchant_id&page=1&pageSize=20&status=fullpaid,settled&chainName=base,eth" \
  -H "X-API-Key: mk_live_your_api_key" \
  -H "X-App-Client: merchant-client"

### List Success Response

{
  "success": true,
  "data": {
    "items": [
      {
        "orderId": "ord_your_order_id",
        "merchantId": "mch_your_merchant_id",
        "status": "fullpaid",
        "amountUsd": "49.00",
        "totalPaidAmountUsd": "49.00",
        "chainName": "base",
        "chainId": 8453,
        "tokenSymbol": "USDC",
        "tokenAddress": "0x...",
        "tokenDecimals": 6,
        "orderAddress": "0x2222222222222222222222222222222222222222",
        "paymentUrl": "https://pay.stafiel.com/pay/ps_live_example",
        "expiresAt": "2026-05-19T12:30:00.000Z",
        "createdAt": "2026-05-19T12:00:00.000Z",
        "updatedAt": "2026-05-19T12:05:00.000Z",
        "metadata": {
          "customerReference": "CUS-8842"
        }
      }
    ],
    "chains": [],
    "total": 1,
    "page": 1,
    "pageSize": 20,
    "hasMore": false,
    "createdAtFrom": null,
    "createdAtTo": null,
    "merchantId": "mch_your_merchant_id"
  }
}

### List Response Fields

Field
Type
Description

items
array
Orders visible to the API key for the requested merchant and filters.

chains
array
Chain metadata included for filter or display context. API integrations may ignore it.

total
number
Total matching order count.

page
number
Current page number.

pageSize
number
Number of orders requested per page.

hasMore
boolean
Whether another page of results is available.

createdAtFrom
string or null
Applied lower creation-time filter.

createdAtTo
string or null
Applied upper creation-time filter.

merchantId
string
Merchant ID for single-merchant API key responses.

### Pagination Notes

List responses use page-based pagination. For batch syncs, set createdAtTo at
the start of the sync and keep that value while reading subsequent pages. This
prevents newly created orders from changing the result window while your sync is
in progress.

### Order Item Fields

Field
Type
Description

orderId
string
Stafiel order ID.

merchantId
string
Merchant ID that owns the order.

status
string
Current business status of the order.

amountUsd
string or null
Original checkout amount.

totalPaidAmountUsd
string or null
Total recorded payment amount when token decimals are known.

chainName
string or null
Canonical public chain label.

chainId
number or null
Numeric chain ID when available.

tokenSymbol
string or null
Token symbol for the order.

tokenAddress
string or null
Token contract or mint address.

tokenDecimals
number or null
Token decimals used for amount formatting.

orderAddress
string or null
Payment contract or payment address.

paymentUrl
string or omitted
Hosted checkout URL, if still available for the order.

expiresAt
string
ISO 8601 expiration timestamp.

createdAt
string
ISO 8601 creation timestamp.

updatedAt
string
ISO 8601 update timestamp.

metadata
object or null
Sanitized order metadata.

## Get Order Details

### Endpoint

GET /api/v1/orders/{orderId}

### Parameters

Field
Required
Default
Description

orderId
Yes
None
Path parameter. Stafiel order ID or supported order reference.

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?merchantId=mch_your_merchant_id" \
  -H "X-API-Key: mk_live_your_api_key" \
  -H "X-App-Client: merchant-client"

### Detail Success Response

{
  "success": true,
  "data": {
    "orderId": "ord_your_order_id",
    "merchantId": "mch_your_merchant_id",
    "status": "fullpaid",
    "amountUsd": "49.00",
    "totalPaidAmountUsd": "49.00",
    "chainName": "base",
    "chainId": 8453,
    "tokenSymbol": "USDC",
    "tokenAddress": "0x...",
    "tokenDecimals": 6,
    "orderAddress": "0x2222222222222222222222222222222222222222",
    "paymentUrl": "https://pay.stafiel.com/pay/ps_live_example",
    "expiresAt": "2026-05-19T12:30:00.000Z",
    "createdAt": "2026-05-19T12:00:00.000Z",
    "updatedAt": "2026-05-19T12:05:00.000Z",
    "metadata": {
      "customerReference": "CUS-8842"
    }
  }
}

### Detail Response Fields

Field
Type
Description

orderId
string
Stafiel order ID.

merchantId
string
Merchant ID that owns the order.

status
string
Current business status of the order.

amountUsd
string
Original checkout amount.

totalPaidAmountUsd
string
Total recorded payment amount displayed to 2 decimals.

chainName
string
Canonical public chain label.

chainId
number or null
Numeric chain ID when available.

tokenSymbol
string
Token symbol for the order.

tokenAddress
string or null
Token contract or mint address.

tokenDecimals
number or null
Token decimals used for amount formatting.

orderAddress
string or null
Payment contract or payment address.

paymentUrl
string or omitted
Hosted checkout URL, if still available for the order.

expiresAt
string
ISO 8601 expiration timestamp.

createdAt
string
ISO 8601 creation timestamp.

updatedAt
string
ISO 8601 update timestamp.

metadata
object or null
Sanitized order metadata.

## Order Statuses

The status field can use these values. Do not assume status changes are
strictly linear; use webhooks or repeated API reads to observe the latest state.

Status
Meaning

awaiting_payment
The order is open and waiting for payment.

underpaid
Recorded payment is below the expected amount.

fullpaid
Recorded payment matches the expected amount.

overpaid
Recorded payment is above the expected amount.

expired
The payment window has expired.

settled
Settlement has been recorded.

full_refunded
The order has been fully refunded.

compliance_hold
The order is held by risk or compliance controls.

closed
The order is closed.

## Error Responses

Error responses use this shape:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Order not found"
  }
}

HTTP Status
Code
Meaning

400
VALIDATION_ERROR
Query parameter is invalid or 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 does not exist or is not visible.

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