Get orders by a partner key

List of orders for a specific partner key.

All parameters are optional filters for the list of orders that will be returned. We recommend specifying as many filters as possible. If you do not specify query parameters, the method returns a full list of orders.

HTTP request

get

/v1/orders

Request

Header parameters

Requires authentification.

Query parameters

Name	Type	Required	Description
externalUserId	array of strings	false	Array of external user IDs that you have sent in request POST /orders or /sell/orders in the externalUserID field.
limit	number	false	Set the maximum number of items. The limit is from 1 to 100.
offset	number	false	Skip items to start. Minimum: 0.
orderId	array of strings	false	Array of order IDs that have been received in response POST /orders or /sell/orders in the orderID field.
externalOrderId	array of strings	false	Array of external order IDs that you have sent in request POST /orders or /sell/orders in the externalOrderId field.
startDate	string	false	Start date for filtering orders in ISO format in UTC time zone.
endDate	string	false	End date for filtering orders in ISO format in UTC time zone.
status	array of strings	false	Array of order statuses. Possible values.

Sample cURL

curl --location --request GET
'https://fiat-api.changelly.com/v1/orders?startDate=2025-09-18T11:00:00.000Z&orderId=882f0a1a-05eb-4d38-97a4-44f84c0fc5f5&externalUserId=Cointelegraph&externalOrderId=9b32a9f2-4d0d-45a0-9eef-faaa7b5b62dd&status=expired&offset=0&limit=30'
--header 'X-Api-Key: {{apiKey}}'
--header 'X-Api-Signature: {{signature}}'

Response

info

If any of the parameters are not provided, they will be returned with the null value.

Response params

Name	Type	Required	Description
orders	array of objects	true	Array of orders.
limit	integer	true	Limit of orders per request.
offset	integer	true	Offset for paginating orders.
total	integer	true	Total number of orders.

order item schema

Name	Type	Required	Description
amountFrom	string	true	Amount of currency the user is going to pay.
country	string	true	Country ISO 3166-1 code (Alpha-2).
state	string	true	State ISO 3166-2 code. Is required if provided country is US.
createdAt	date-time	true	Time in ISO 8601 format.
updatedAt	date-time	true	Time in ISO 8601 format.
currencyFrom	string	true	Ticker of the payin currency in uppercase.
currencyTo	string	true	Ticker of the payout currency in uppercase.
externalUserId	string	true	User ID provided by you.
ip	string	true	User's IP address.
metadata	object	true	Metadata object, which can contain any parameters you need.
orderId	string	true	Internal order ID provided by Fiat API.
externalOrderId	string	true	Order ID provided by you.
payinAmount	string	true	Payin amount.
payoutAmount	string	true	Estimated payout amount.
payinCurrency	string	true	Ticker of the payin currency.
payoutCurrency	string	true	Ticker of the payout currency.
paymentMethod	string	true	The payment method code. Possible values
providerCode	string	true	The On-Ramp or Off-Ramp provider code. Possible values.
redirectUrl	string	true	URL to the provider's purchase page.
refundAddress	string	true	Recipient refund address.
status	string	true	Current order status. Possible values.
transactionHash	string	true	Transaction hash in the blockchain.
type	string	true	Order type. Enum: buy/sell.
userAgent	string	true	User Agent.
walletAddress	string	true	Recipient wallet address.
walletExtraId	string	true	Property required for wallet addresses of currencies that use an additional ID for transaction processing (XRP, XLM, EOS, BNB).

Sample response

application/json

{
  "orders": [
    {
      "redirectUrl": "https://buy.moonpay.com/changelly?...",
      "orderId": "882f0a1a-05eb-4d38-97a4-44f84c0fc5f5",
      "externalUserId": "Cointelegraph",
      "externalOrderId": "9b32a9f2-4d0d-45a0-9eef-faaa7b5b62dd",
      "providerCode": "moonpay",
      "type": "buy",
      "currencyFrom": "THB",
      "currencyTo": "ETH",
      "amountFrom": "1000",
      "country": "TH",
      "state": null,
      "ip": null,
      "walletAddress": "...",
      "walletExtraId": null,
      "refundAddress": null,
      "paymentMethod": "card",
      "userAgent": null,
      "metadata": null,
      "createdAt": "2025-09-18T11:46:45.994Z",
      "status": "expired",
      "payinAmount": null,
      "payoutAmount": null,
      "payinCurrency": null,
      "payoutCurrency": null,
      "updatedAt": "2025-09-18T15:06:07.672Z",
      "transactionHash": "ab123********************************45890e9831e9e16"
    }
  ],
  "total": 55,
  "limit": 30,
  "offset": 0
}

Error response

Error response parameters

Check the error response schema.

Possible error types in the errorType item:

Type	Description
validation	Validation error.

The errorDetails item schema:

Name	Type	Required	Description
cause	string	true	Error cause. For example, it can equal the missing request parameter for the validation error type.
value	string	true	Error value.

Error codes

Code	Message
400	Bad request
401	Unauthorized
404	Not found
429	Too many requests
500	Internal server error

400

Bad Request

{
  "errorType": "validation",
  "errorMessage": "Validation error",
  "errorDetails": [
    {
      "cause": "status",
      "value": "each value in status must be one of the following values: created, pending, hold, refunded, expired, failed, complete"
    }
  ]
}

401

Unauthorized

{
  "errorType": "unauthorized",
  "errorMessage": "Unauthorized",
  "errorDetails": null
}

404

Not Found

{
  "errorType": "notFound",
  "errorMessage": "Not found",
  "errorDetails": null
}

429

Too Many Requests

{
  "errorType": "tooManyRequests",
  "errorMessage": "Too many requests",
  "errorDetails": null
}

500

Internal Server Error

{
  "errorType": "internalServerError",
  "errorMessage": "Internal Server Error",
  "errorDetails": null
}