List Orders API

Retrieve a paginated list of orders with comprehensive filtering options for order management and reporting.

Endpoint

GET /api/v1/orders

Authentication: API Key + Secret required

Request Headers

X-API-Key: sk_live_abc123def456
X-API-Secret: your-secret-here

Query Parameters

Parameter	Type	Default	Required	Description
`page`	integer	1	No	Page number for pagination (min: 1)
`limit`	integer	10	No	Number of results per page (min: 1, max: 100)
`status`	string	-	No	Filter by order status
`product_id`	integer	-	No	Filter orders by product ID

Status Values

Orders can have the following statuses:

Status	Description	Wallet Deduction	Vouchers Available
`PENDING`	Order created, processing in progress	Yes (Deducted)	No (Not yet)
`PROCESSING`	Order currently being fulfilled	Yes (Deducted)	No (Not yet)
`DELIVERED`	Order completed successfully	Yes (Deducted)	Yes (Available)
`PARTIALLY_DELIVERED`	Some vouchers delivered	Yes (Deducted)	Yes (Some available)
`FAILED`	Order processing failed	No (Refunded)	No (None)
`CANCELLED`	Order was cancelled	No (Refunded)	No (None)

Status Flow:

Order Creation → PENDING → PROCESSING → DELIVERED
                    ↓
                 FAILED (if processing fails)

Note: The status filter is case-insensitive. You can use either uppercase (e.g., PENDING) or lowercase (e.g., pending) values.

Response

Success Response

Status Code: 200 OK

Response Headers:

X-Page: 1
X-Per-Page: 10
X-Total-Count: 150
X-Total-Pages: 15

Response Body:

[
  {
    "id": 12345,
    "product_name": "Amazon Gift Card",
    "currency": "USD",
    "reference_code": "ORD-ABC123",
    "transaction_id": 789,
    "product_id": 1001,
    "denomination": "25.00",
    "quantity": 1,
    "amount": "25.00",
    "status": "delivered",
    "email": "customer@example.com",
    "mobile": {
      "mobile_country_code": "+1",
      "mobile_number": "5551234567"
    },
    "placed_at": "2024-01-15T10:30:00Z"
  },
  {
    "id": 12346,
    "product_name": "Google Play Gift Card",
    "currency": "EUR",
    "reference_code": "ORD-DEF456",
    "transaction_id": 790,
    "product_id": 2001,
    "denomination": "50.00",
    "quantity": 2,
    "amount": "100.00",
    "status": "processing",
    "email": "user@example.com",
    "mobile": {
      "mobile_country_code": "+44",
      "mobile_number": "7700900000"
    },
    "placed_at": "2024-01-15T11:45:00Z"
  }
]

Response Fields

Field	Type	Description
`id`	integer	Unique order identifier
`product_name`	string	Display name of the ordered product
`currency`	string	ISO 4217 currency code
`reference_code`	string	Unique order reference for tracking
`transaction_id`	integer	Associated payment transaction ID
`product_id`	integer	Product catalog identifier
`denomination`	string	Unit value with 2 decimal places
`quantity`	integer	Number of units ordered
`amount`	string	Total order amount with 2 decimal places
`status`	string	Current order status
`email`	string	Customer email address (may be null)
`mobile`	object	Customer mobile information
`mobile.mobile_country_code`	string	International dialing code
`mobile.mobile_number`	string	Phone number without country code
`placed_at`	string	Order timestamp in RFC3339 format

Pagination Headers

Header	Description
`X-Page`	Current page number
`X-Per-Page`	Items per page
`X-Total-Count`	Total number of orders
`X-Total-Pages`	Total number of pages

Examples

# Get first page of orders with default pagination
curl -X GET "{{host}}/api/v1/orders" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

# Filter by delivered status with custom pagination
curl -X GET "{{host}}/api/v1/orders?status=delivered&limit=20&page=1" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

# Get orders for specific product
curl -X GET "{{host}}/api/v1/orders?product_id=1001" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

# Combine filters
curl -X GET "{{host}}/api/v1/orders?status=delivered&product_id=1001&limit=50" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

Error Responses

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or expired access token"
}

404 Not Found

{
  "error": "not_found",
  "message": "No Matching Result Found!"
}

429 Too Many Requests

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please try again later."
}

Filtering Best Practices

Use Specific Filters - Apply filters to reduce response size and improve performance
Paginate Large Results - Use appropriate page sizes (10-50 items) for better performance
Cache Results - Cache order lists that don't change frequently
Monitor Headers - Check pagination headers to handle multi-page results
Combine Filters - Use multiple filters together for precise results

Performance Tips

Optimal Page Sizes

Interactive UI: 10-25 items per page
Bulk Processing: 50-100 items per page
Reports: Up to 100 items per page

Caching Strategy

Cache delivered orders (rarely change)
Don't cache pending/processing orders
Implement cache invalidation on status changes

Parallel Requests

When fetching multiple pages, use parallel requests with rate limit awareness:

List Orders API

On this page