# Settlements API

> Query settlement records for an order.

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

Use the Settlements API to query settlement records for an order.

## Endpoint

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

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

If no settlement record exists yet, data can be null.

## Success Response

{
  "success": true,
  "data": {
    "txHash": "0xabc123...",
    "merchantAmount": "48.51",
    "platformAmount": "0.49",
    "status": "settled",
    "isVerified": true,
    "merchantAddress": "0x3333333333333333333333333333333333333333",
    "createdAt": "2026-05-19T12:20:00.000Z",
    "updatedAt": "2026-05-19T12:20:30.000Z"
  }
}

## Response Fields

Field
Type
Description

txHash
string or null
Settlement transaction hash.

merchantAmount
string or null
Amount settled to the merchant wallet, displayed to 2 decimals.

platformAmount
string or null
Platform fee amount, displayed to 2 decimals.

status
string or null
Settlement status: pending, settled, or failed.

isVerified
boolean or null
Whether the settlement record has been verified.

merchantAddress
string or null
Merchant settlement address snapshot for the order.

createdAt
string
ISO 8601 creation timestamp.

updatedAt
string or null
ISO 8601 update timestamp.

## Settlement Address Snapshot

The merchant settlement address is taken from the order's creation snapshot. A
later wallet configuration change does not rewrite the settlement address for an
existing order.

## Error Responses

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.