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

limit · integer · default: "20"

Maximum number of orders to return per page. Range: 1-100.

offset · integer · default: "0"

Number of orders to skip. Use for pagination.

cursor · string

Cursor-based pagination token. More efficient for large datasets.

Sorting Parameters

sort · string · default: "created_at"

Sort field. Options: created_at, updated_at, order_number, total_amount, status, customer_email

order · string · default: "desc"

Sort direction. Options: asc, desc

Filter Parameters

Status Filters

status · string

Filter by order status. Options: pending, processing, shipped, delivered, cancelled, refunded

status_in · array

Filter by multiple statuses. Example: status_in=pending,processing

Date Filters

created_after · string

Orders created after this date (ISO 8601 format: 2024-01-01T00:00:00Z)

created_before · string

Orders created before this date (ISO 8601 format: 2024-12-31T23:59:59Z)

updated_after · string

Orders updated after this date

shipped_after · string

Orders shipped after this date

Customer Filters

customer_email · string

Filter by exact customer email

customer_id · string

Filter by customer ID

customer_tier · string

Filter by customer tier. Options: bronze, silver, gold, platinum

Financial Filters

total_amount_gte · number

Orders with total amount greater than or equal to this value

total_amount_lte · number

Orders with total amount less than or equal to this value

currency · string

Filter by currency code (ISO 4217). Example: USD, EUR, GBP

Location Filters

shipping_country · string

Filter by shipping country code (ISO 3166-1). Example: US, CA, GB

shipping_state · string

Filter by shipping state/province

fulfillment_location · string

Filter by fulfillment center ID

Product Filters

sku · string

Filter orders containing specific SKU

product_category · string

Filter orders containing products from specific category

Source Filters

source · string

Filter by order source. Options: website, mobile_app, marketplace, phone, retail

channel · string

Filter by sales channel

Search

search · string

Full-text search across order number, customer name, email, and product names

Advanced Filters

has_returns · boolean

Filter orders that have associated returns

is_gift · boolean

Filter gift orders

risk_level · string

Filter by fraud risk level. Options: low, medium, high

priority · string

Filter by order priority. Options: low, normal, high, urgent

Include Parameters

include · array

Include related data. Options: line_items, customer, shipping_address, billing_address, payments, returns, fulfillments

Response

orders · array

An array of order objects.

Show Order Object

id · string

This is the id of the order.

name · string

This is the name of the order.

order_number · string

This is the order number.

created_date · string

This is the date the order was created.

updated_date · string

This is the date the order was last updated.

order_status · string

This is the status of the order.

imported_status · string

This is the imported status of the order.

delivery_date · string

This is the delivery date of the order.

ordered_by · string

This is the person who ordered.

delivery_address · string

This is the delivery address for the order.

notes · string

These are additional notes for the order.

imported_date · string

This is the date the order was imported.

customer_number · string

This is the customer number associated with the order.

customer_name · string

This is the name of the customer.

import · boolean

This indicates if the order was imported.

customer_email · string

This is the email of the customer.

source · string

This is the source of the order.

buyer_email · string

This is the email of the buyer.

buyer_message · string

This is a message from the buyer.

cancel_order_sla_time · string

This is the SLA time for cancelling the order.

cancel_reason · string

This is the reason for cancellation, if applicable.

cancellation_initiator · string

This is who initiated the cancellation, if applicable.

fulfillment_type · string

This is the type of fulfillment for the order.

delivery_type · string

This is the type of delivery for the order.

is_cod · boolean

This indicates if the order is cash on delivery.

is_replacement_order · boolean

This indicates if this is a replacement order.

seller_note · string

This is a note from the seller.

status · string

This is the current status of the order.

tracking_number · string

This is the tracking number for the order.

warehouse_id · string

This is the id of the warehouse handling the order.

order_line_items · array

These are the line items associated with the order.

Show Order Line Item Object

id · string

This is the id of the order line item.

wholesale_order_id · string

This is the id of the associated wholesale order.

product_name · string

This is the name of the product.

quantity · string

This is the quantity of the product ordered.

created_date · string

This is the date the line item was created.

updated_date · string

This is the date the line item was last updated.

unit · string

This is the unit of measurement for the product.

product_id · string

This is the id of the product.

brand · string

This is the brand of the product.

stock_code · string

This is the stock code of the product.

size · string

This is the size of the product.

status · string

This is the status of the line item.

sale_price · integer

This is the sale price of the product.

seller_discount · integer

This is the discount offered by the seller.

seller_sku · string

This is the seller’s SKU for the product.

sku_id · string

This is the SKU id of the product.

sku_image · string

This is the image URL for the product SKU.

sku_name · string

This is the name of the product SKU.

sku_type · string

This is the type of the product SKU.

original_price · integer

This is the original price of the product.

total_count · integer

The total number of orders matching the query parameters.

Basic Pagination

curl -X GET "https://api.stateset.com/v1/orders?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "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": "[e-mail]",
      "source": "Online Store",
      "buyer_email": "[e-mail]",
      "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
  }
}