List Orders

Retrieve orders with advanced filtering, pagination, and sorting capabilities

GET /v1/orders

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
  }
}

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
  }
}