> For the complete documentation index, see [llms.txt](https://docs.fonbnk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fonbnk.com/server-to-server/api-endpoints/get-orders.md).
# Get orders
## \[GET] /api/v2/orders
Lists your orders with cursor pagination and optional filters.
Request query params type:
{% code overflow="wrap" expandable="true" %}
```typescript
type QueryParams = {
limit: number,// required, 1 to 100
cursor?: string,// the nextCursor from the previous page
userEmail?: string,
status?: OrderStatus | OrderStatus[],
fromDate?: number,// unix timestamp in milliseconds
toDate?: number,// unix timestamp in milliseconds
depositCurrencyCode?: string,
depositPaymentChannel?: PaymentChannel | PaymentChannel[],
depositCurrencyType?: CurrencyType | CurrencyType[],
payoutCurrencyCode?: string,
payoutPaymentChannel?: PaymentChannel | PaymentChannel[],
payoutCurrencyType?: CurrencyType | CurrencyType[],
depositUserWalletAddress?: string,
payoutUserWalletAddress?: string,
depositUserPhoneNumber?: string,
payoutUserPhoneNumber?: string,
}
```
{% endcode %}
How the filters behave:
* `limit` is the only required param, and must be between **1 and 100**.
* `status`, `depositPaymentChannel`, `depositCurrencyType`, `payoutPaymentChannel` and `payoutCurrencyType` each accept **one value or several**. Repeat the param to pass a list: `?status=payout_successful&status=payout_failed`.
* `fromDate` and `toDate` are unix timestamps in **milliseconds**. `fromDate` must not be later than `toDate`.
* Phone numbers are normalised before matching, so any format that resolves to the same number works.
* Every filter is scoped to your own orders — there is no way to read another merchant's.
Request URL example:
{% code overflow="wrap" %}
```
GET /api/v2/orders?limit=25&status=payout_successful&status=payout_failed&depositCurrencyType=fiat&fromDate=1764201600000
```
{% endcode %}
### Response
{% code overflow="wrap" expandable="true" %}
```typescript
type Response = {
nextCursor: string | null; // null on the last page
list: Order[]; // same object as Get order returns
}
```
{% endcode %}
Each entry of `list` is the same `Order` object [Get order](/server-to-server/api-endpoints/get-order.md) returns, field for field — that page has the full type and a complete example.
{% hint style="warning" %}
**`nextCursor` is always present.** On the last page it is `null`, not missing. Page by passing it back as `cursor` and stop when it is `null` — a loop that tests whether the key exists never terminates.
{% endhint %}
{% hint style="info" %}
Polling this endpoint is not the way to track a live order. Use the [webhook](/server-to-server/webhooks.md) for status changes, and keep this for reconciliation and back-office views.
{% endhint %}
Response example, trimmed to show the envelope and the fields that differ between two sandbox orders:
{% code overflow="wrap" expandable="true" %}
```json
{
"nextCursor": "69283d079061f4031ad1ba03",
"list": [
{
"_id": "69283e024a1db009177f2146",
"countryIsoCode": "KE",
"userId": "69283c0518613bc9de730cb4",
"userEmail": "testuser.ke@fonbnk.com",
"status": "deposit_canceled",
"deposit": {
"paymentChannel": "mobile_money",
"currencyType": "fiat",
"currencyCode": "KES",
"currencyDetails": {
"countryIsoCode": "KE",
"carrier": { "code": "ke_safaricom", "name": "Safaricom Kenya", "_id": "618e43914f57e07d255ff353" }
},
"cashout": {
"amountBeforeFees": 135,
"amountAfterFees": 130,
"amountBeforeFeesUsd": 1.037584,
"amountAfterFeesUsd": 0.999155,
"exchangeRate": 130.11,
"exchangeRateAfterFees": 135.1142,
"totalChargedFees": 4.73,
"totalChargedFeesUsd": 0.036354
},
"providedFieldsToCreateOrder": {
"phoneNumber": "254712345678",
"carrierCode": "ke_safaricom"
},
"transferInstructions": {
"type": "stk_push",
"intermediateActionAttempts": 1,
"intermediateActionMaxAttempts": 3,
"intermediateActionExecuted": true,
"isIntermediateActionAvailable": true,
"transferDetails": [
{ "id": "amountToSend", "label": "Amount to send", "value": "135" }
],
"fieldsToConfirmOrder": []
}
},
"payout": {
"paymentChannel": "crypto",
"currencyType": "crypto",
"currencyCode": "POLYGON_USDT",
"currencyDetails": {
"network": "POLYGON",
"asset": "USDT",
"contractAddress": "0x3b3a06b48119c035a2e86afdb69d9ad930643b3d"
},
"cashout": {
"amountBeforeFees": 1.000645,
"amountAfterFees": 1,
"amountBeforeFeesUsd": 1.000645,
"amountAfterFeesUsd": 1,
"exchangeRate": 1,
"exchangeRateAfterFees": 1.0006
},
"providedFieldsToCreateOrder": {
"blockchainWalletAddress": "0x5b7ae3c6c87f4a3f94b35c77233b13191ebfad20"
}
},
"statusChangeLogs": [
{ "newStatus": "deposit_canceled", "date": "2025-11-27T12:03:20.472Z" }
],
"createdAt": "2025-11-27T12:03:14.753Z",
"updatedAt": "2025-11-27T12:03:20.473Z",
"expiresAt": "2025-11-27T12:08:14.702Z"
},
{
"_id": "69283d079061f4031ad1ba03",
"status": "payout_successful",
"payout": {
"transaction": {
"meta": {
"transactionHash": "0xe168c39bf7165c0eaa88e4df1e21e987666e44f11f2bea6f9be1c145f382dade",
"fromAddress": "0xdc9cbad0c43f912a66cd44cd22a15c04368e659f",
"toAddress": "0x5b7ae3c6c87f4a3f94b35c77233b13191ebfad20"
}
}
},
"statusChangeLogs": [
{ "oldStatus": "deposit_awaiting", "newStatus": "deposit_validating", "date": "2025-11-27T12:01:43.660Z" },
{ "oldStatus": "deposit_validating", "newStatus": "deposit_successful", "date": "2025-11-27T12:02:00.770Z" },
{ "oldStatus": "deposit_successful", "newStatus": "payout_pending", "date": "2025-11-27T12:02:01.306Z" },
{ "oldStatus": "payout_pending", "newStatus": "payout_successful", "date": "2025-11-27T12:02:19.053Z" }
],
"createdAt": "2025-11-27T11:59:03.754Z",
"updatedAt": "2025-11-27T12:02:19.124Z",
"expiresAt": "2025-11-27T12:04:03.673Z"
}
]
}
```
{% endcode %}
The second entry is abbreviated to the fields that differ — a real response repeats the whole object for every order.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.fonbnk.com/server-to-server/api-endpoints/get-orders.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.