> ## Documentation Index > Fetch the complete documentation index at: https://docs.stateset.com/llms.txt > Use this file to discover all available pages before exploring further. # List Orders > Retrieve orders with advanced filtering, pagination, and sorting capabilities This endpoint supports comprehensive filtering, pagination, and sorting. Use query parameters to efficiently retrieve the exact orders you need. ## Pagination Parameters Maximum number of orders to return per page. Range: 1-100. Number of orders to skip. Use for pagination. Cursor-based pagination token. More efficient for large datasets. ## Sorting Parameters Sort field. Options: `created_at`, `updated_at`, `order_number`, `total_amount`, `status`, `customer_email` Sort direction. Options: `asc`, `desc` ## Filter Parameters ### Status Filters Filter by order status. Options: `pending`, `processing`, `shipped`, `delivered`, `cancelled`, `refunded` Filter by multiple statuses. Example: `status_in=pending,processing` ### Date Filters Orders created after this date (ISO 8601 format: `2024-01-01T00:00:00Z`) Orders created before this date (ISO 8601 format: `2024-12-31T23:59:59Z`) Orders updated after this date Orders shipped after this date ### Customer Filters Filter by exact customer email Filter by customer ID Filter by customer tier. Options: `bronze`, `silver`, `gold`, `platinum` ### Financial Filters Orders with total amount greater than or equal to this value Orders with total amount less than or equal to this value Filter by currency code (ISO 4217). Example: `USD`, `EUR`, `GBP` ### Location Filters Filter by shipping country code (ISO 3166-1). Example: `US`, `CA`, `GB` Filter by shipping state/province Filter by fulfillment center ID ### Product Filters Filter orders containing specific SKU Filter orders containing products from specific category ### Source Filters Filter by order source. Options: `website`, `mobile_app`, `marketplace`, `phone`, `retail` Filter by sales channel ### Search Full-text search across order number, customer name, email, and product names ### Advanced Filters Filter orders that have associated returns Filter gift orders Filter by fraud risk level. Options: `low`, `medium`, `high` Filter by order priority. Options: `low`, `normal`, `high`, `urgent` ### Include Parameters Include related data. Options: `line_items`, `customer`, `shipping_address`, `billing_address`, `payments`, `returns`, `fulfillments` ### Response An array of order objects. This is the id of the order. This is the name of the order. This is the order number. This is the date the order was created. This is the date the order was last updated. This is the status of the order. This is the imported status of the order. This is the delivery date of the order. This is the person who ordered. This is the delivery address for the order. These are additional notes for the order. This is the date the order was imported. This is the customer number associated with the order. This is the name of the customer. This indicates if the order was imported. This is the email of the customer. This is the source of the order. This is the email of the buyer. This is a message from the buyer. This is the SLA time for cancelling the order. This is the reason for cancellation, if applicable. This is who initiated the cancellation, if applicable. This is the type of fulfillment for the order. This is the type of delivery for the order. This indicates if the order is cash on delivery. This indicates if this is a replacement order. This is a note from the seller. This is the current status of the order. This is the tracking number for the order. This is the id of the warehouse handling the order. These are the line items associated with the order. This is the id of the order line item. This is the id of the associated wholesale order. This is the name of the product. This is the quantity of the product ordered. This is the date the line item was created. This is the date the line item was last updated. This is the unit of measurement for the product. This is the id of the product. This is the brand of the product. This is the stock code of the product. This is the size of the product. This is the status of the line item. This is the sale price of the product. This is the discount offered by the seller. This is the seller's SKU for the product. This is the SKU id of the product. This is the image URL for the product SKU. This is the name of the product SKU. This is the type of the product SKU. This is the original price of the product. The total number of orders matching the query parameters. ```bash Basic Pagination theme={null} curl -X GET "https://api.stateset.com/v1/orders?limit=20&offset=0" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" ``` ```bash Advanced Filtering theme={null} curl -X GET "https://api.stateset.com/v1/orders" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -G \ --data-urlencode "status_in=processing,shipped" \ --data-urlencode "created_after=2024-01-01T00:00:00Z" \ --data-urlencode "total_amount_gte=50.00" \ --data-urlencode "shipping_country=US" \ --data-urlencode "include=line_items,customer" \ --data-urlencode "sort=total_amount" \ --data-urlencode "order=desc" \ --data-urlencode "limit=50" ``` ```bash Search and Filter theme={null} curl -X GET "https://api.stateset.com/v1/orders" \ -H "Authorization: Bearer YOUR_API_KEY" \ -G \ --data-urlencode "search=john@example.com" \ --data-urlencode "status=delivered" \ --data-urlencode "created_after=2024-01-01" \ --data-urlencode "created_before=2024-01-31" ``` ```bash Cursor-based Pagination theme={null} curl -X GET "https://api.stateset.com/v1/orders?cursor=eyJpZCI6Im9yZF8xMjM0NSIsImNyZWF0ZWRfYXQiOiIyMDI0LTAxLTE1VDEwOjMwOjAwWiJ9&limit=25" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```graphQL GraphQL theme={null} query ($limit: Int!, $offset: Int!, $sort: String!, $order: String!) { orders(limit: $limit, offset: $offset, sort: $sort, order: $order) { id name order_number created_date updated_date order_status imported_status delivery_date ordered_by delivery_address notes imported_date customer_number customer_name import customer_email source buyer_email buyer_message cancel_order_sla_time cancel_reason cancellation_initiator fulfillment_type delivery_type is_cod is_replacement_order seller_note status tracking_number warehouse_id order_line_items { id wholesale_order_id product_name quantity created_date updated_date unit product_id brand stock_code size status sale_price seller_discount seller_sku sku_id sku_image sku_name sku_type original_price } } total_count } ``` ```js Basic Pagination theme={null} const orders = await stateset.orders.list({ limit: 20, offset: 0, sort: 'created_at', order: 'desc' }); ``` ```js Advanced Filtering theme={null} const orders = await stateset.orders.list({ status_in: ['processing', 'shipped'], created_after: '2024-01-01T00:00:00Z', total_amount_gte: 50.00, shipping_country: 'US', include: ['line_items', 'customer'], sort: 'total_amount', order: 'desc', limit: 50 }); ``` ```js Pagination Helper Function theme={null} // Paginate through all orders async function getAllOrders(filters = {}) { const allOrders = []; let hasMore = true; let offset = 0; const limit = 100; while (hasMore) { const response = await stateset.orders.list({ ...filters, limit, offset }); allOrders.push(...response.orders); hasMore = response.orders.length === limit; offset += limit; // Add delay to respect rate limits if (hasMore) { await new Promise(resolve => setTimeout(resolve, 100)); } } return allOrders; } // Usage const allProcessingOrders = await getAllOrders({ status: 'processing', created_after: '2024-01-01' }); ``` ```js Cursor-based Pagination theme={null} // More efficient for large datasets async function getOrdersWithCursor(filters = {}) { const allOrders = []; let cursor = null; do { const response = await stateset.orders.list({ ...filters, cursor, limit: 100 }); allOrders.push(...response.orders); cursor = response.next_cursor; } while (cursor); return allOrders; } ``` ```js Real-time Filtering Example theme={null} // Filter orders dynamically based on user input class OrderFilter { constructor(client) { this.client = client; this.cache = new Map(); } async searchOrders(query) { const cacheKey = JSON.stringify(query); if (this.cache.has(cacheKey)) { return this.cache.get(cacheKey); } const filters = this.buildFilters(query); const orders = await this.client.orders.list(filters); // Cache for 5 minutes this.cache.set(cacheKey, orders); setTimeout(() => this.cache.delete(cacheKey), 300000); return orders; } buildFilters(query) { const filters = { limit: 50 }; if (query.search) { filters.search = query.search; } if (query.status && query.status.length > 0) { filters.status_in = query.status; } if (query.dateRange) { filters.created_after = query.dateRange.start; filters.created_before = query.dateRange.end; } if (query.amountRange) { if (query.amountRange.min) filters.total_amount_gte = query.amountRange.min; if (query.amountRange.max) filters.total_amount_lte = query.amountRange.max; } if (query.location) { filters.shipping_country = query.location.country; if (query.location.state) filters.shipping_state = query.location.state; } return filters; } } ``` ```py Python theme={null} orders = stateset.orders.list( limit=10, offset=0, sort='created_date', order='desc' ) ``` ```go Golang theme={null} orders, err := stateset.Orders.List(&stateset.OrderListParams{ Limit: 10, Offset: 0, Sort: "created_date", Order: "desc", }) ``` ```ruby Ruby theme={null} orders = Stateset::Order.list( limit: 10, offset: 0, sort: 'created_date', order: 'desc' ) ``` ```java Java theme={null} OrderListParams params = new OrderListParams.Builder() .setLimit(10) .setOffset(0) .setSort("created_date") .setOrder("desc") .build(); OrderCollection orders = Order.list(params); ``` ```csharp C# theme={null} var orderListOptions = new OrderListOptions { Limit = 10, Offset = 0, Sort = "created_date", Order = "desc" }; var orders = Order.List(orderListOptions); ``` ```php PHP theme={null} $orders = $stateset->orders->list([ 'limit' => 10, 'offset' => 0, 'sort' => 'created_date', 'order' => 'desc' ]); ``` ```http HTTP theme={null} GET /v1/orders?limit=10&offset=0&sort=created_date&order=desc HTTP/1.1 Host: api.stateset.com Content-Type: application/json Authorization: Bearer ``` ```json Response theme={null} { "orders": [ { "id": "ord_1NXWPnCo6bFb1KQto6C8OWvE", "name": "Example Order 1", "order_number": "ORD-12345", "created_date": "2023-08-23T10:00:00Z", "updated_date": "2023-08-23T11:00:00Z", "order_status": "Processing", "imported_status": "Completed", "delivery_date": "2023-08-30T14:00:00Z", "ordered_by": "John Doe", "delivery_address": "123 Main St, Anytown, AN 12345", "notes": "Please handle with care", "imported_date": "2023-08-23T09:00:00Z", "customer_number": "CUST-6789", "customer_name": "John Doe", "import": true, "customer_email": "john.doe@example.com", "source": "Online Store", "buyer_email": "john.doe@example.com", "buyer_message": "Looking forward to receiving the order!", "cancel_order_sla_time": null, "cancel_reason": null, "cancellation_initiator": null, "fulfillment_type": "Standard", "delivery_type": "Home Delivery", "is_cod": false, "is_replacement_order": false, "seller_note": "Thank you for your order", "status": "Processing", "tracking_number": "TRACK-98765", "warehouse_id": "wh_2MXYQoDp7cGc2LRup7D9PXvF", "order_line_items": [ { "id": "oli_3OYZRpEq8dHd3MSvq8E0QYwG", "wholesale_order_id": "ord_1NXWPnCo6bFb1KQto6C8OWvE", "product_name": "Example Product", "quantity": "2", "created_date": "2023-08-23T10:05:00Z", "updated_date": "2023-08-23T10:05:00Z", "unit": "piece", "product_id": "prod_4PZaSqFr9eIe4NTwr9F1RZxH", "brand": "Example Brand", "stock_code": "EX-1234", "size": "Medium", "status": "In Stock", "sale_price": 2999, "seller_discount": 500, "seller_sku": "SKU-5678", "sku_id": "sku_6QAbTrGs0fJf5OUxs0G2SZyI", "sku_image": "https://example.com/images/product.jpg", "sku_name": "Example Product - Medium", "sku_type": "Standard", "original_price": 3499 } ] }, ], "total_count": 1, "has_more": false, "next_cursor": null, "has_more": false, "next_cursor": null, "filters_applied": { "status": "processing", "created_after": "2024-01-01T00:00:00Z" }, "pagination": { "current_page": 1, "per_page": 20, "total_pages": 1 } } ```