🔒
Requires read_order access scope. More access scope

The Get Order List API retrieves a paginated list of orders with filtering capabilities.

This API is especially useful for:

Viewing and managing multiple orders at scale
Filtering orders by status, date ranges, or other criteria
Implementing order management dashboards
Exporting order data for analysis

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Query Parameters

Parameter	Type	Required	Description	Example
`cursor`	string	No	Pagination cursor	`"abc123"`
`page_size`	int32	No	Results per page (1-250)	`50`
`ids`	array[string]	No	Filter by order IDs	`["ord_123","ord_456"]`
`created_at_min`	string	No	Earliest creation date (ISO-8601)	`"2023-01-01T00:00:00Z"`
`created_at_max`	string	No	Latest creation date (ISO-8601)	`"2023-12-31T23:59:59Z"`
`updated_at_min`	string	No	Earliest update date (ISO-8601)	`"2023-06-01T00:00:00Z"`
`updated_at_max`	string	No	Latest update date (ISO-8601)	`"2023-06-30T23:59:59Z"`
`placed_at_min`	string	No	Earliest payment date (ISO-8601)	`"2023-06-01T00:00:00Z"`
`placed_at_max`	string	No	Latest payment date (ISO-8601)	`"2023-06-30T23:59:59Z"`
`status`	array[string]	No	Filter by order status	`["open","paid"]`
`fulfillment_status`	array[string]	No	Filter by fulfillment state	`["fulfilled"]`
`financial_status`	array[string]	No	Filter by payment state	`["paid","pending"]`
`recovery_status`	array[string]	No	Filter by recovery state	`["success"]`
`location_id`	string	No	Filter by fulfillment location	`"loc_123"`
`keyword`	string	No	Search term	`"VIP customer"`
`keyword_scope_fields`	array[string]	No	Fields to search	`["name","email"]`
`sort_by`	string	No	Sort field	`"created_at"`
`sort_direction`	string	No	Sort order	`"desc"`
`customer_id`	string	No	Filter by customer ID	`"cust_123"`

Response Explanation

Public Response Parameters

📘
Public Response Parameters

Successful Response

Parameter	Type	Example	Description
`code`	string	`"success"`	Status code of the API response
`message`	string	`"Order retrieved successfully"`	Descriptive message about the response
`data.orders`	array of object	-	Complete order object containing all details
`data.cursor`	string		Cursor for pagination.
`data.has_more`	boolean	`true`	`true` if there is more data after the cursor, else `false`

Order Object

Parameter	Type	Example	Description
`id`	string	`"ord_123"`	Order ID
`created_at`	string	`"2023-01-01T00:00:00Z"`	Creation time
`updated_at`	string	`"2023-01-01T00:00:00Z"`	Update time
`note`	string	`"Gift note"`	Merchant note
`number`	string	`"#1001"`	Order number
`total_price`	string	`"100.00"`	Total price
`sub_total`	string	`"90.00"`	Subtotal
`currency`	string	`"USD"`	Currency
`financial_status`	string	`"paid"`	Payment status
`status`	string	`"fulfilled"`	Order status
`cancelled_at`	string		Cancel time
`cancel_reason`	string		Cancel reason
`payment_method`	string		Payment method
`fulfillment_status`	string	`"fulfilled"`	Fulfillment status
`customer_deleted_at`	string		Customer deletion time
`deleted_at`	string		Order deletion time
`placed_at`	string	`"2023-01-01T00:00:00Z"`	Payment time
`tags`	string	`"vip"`	Order tags
`buyer_accepts_marketing`	boolean	`true`	Marketing consent
`code_discount_total`	string	`"10.00"`	Code discounts
`customer_note`	string	`"Handle with care"`	Customer note
`total_discount`	string	`"10.00"`	Total discounts
`total_tax`	string	`"5.00"`	Product taxes
`total_shipping`	string	`"5.00"`	Shipping cost
`line_items`	array[object]	-	Line items
`payment_line`	object	-	Payment line
`shipping_line`	object	-	Shipping line
`billing_address`	object	-	Billing address
`shipping_address`	object	-	Shipping address
`fulfillments`	array[object]	-	Fulfillments
`customer`	object	-	Customer info
`refer_info`	string	`"google"`	Referral info
`sales_platform`	string	`"web"`	Sales platform
`total_refund_price`	string	`"0.00"`	Refunded amount
`primary_market_price`	object	-	Market pricing
`total_tip_received`	string	`"5.00"`	Tips received
`discount_applications`	string	`"promo10"`	Discount details
`refund_status`	string	`"none"`	Refund status
`email_status`	string	`"sent"`	Email status
`recovery_status`	string	`"success"`	Recovery status
`total_paid`	string	`"100.00"`	Total paid amount
`payment_lines`	array[object]	-	Payment lines
`gift_card_total`	string	`"0.00"`	Gift card amount
`logistics_code`	string	`"DHL123"`	Logistics code
`shipping_tax_total`	string	`"1.00"`	Shipping tax
`location_line`	object	-	Location info
`additional_total`	string	`"0.00"`	Additional fees
`additional_prices`	array[object]	-	Fee details
`config`	object	-	Configuration
`checkout_url`	string	`"https://..."`	Checkout URL
`duty_total`	string	`"0.00"`	Duty fees

Fulfillment Object

Parameter	Type	Example	Description
`id`	string	`"ful_12345"`	Fulfillment/shipment ID
`order_id`	string	`"ord_123"`	Associated order ID
`status`	string	`"shipped"`	Current fulfillment status
`created_at`	string	`"2023-01-01T00:00:00Z"`	Creation timestamp
`updated_at`	string	`"2023-01-02T00:00:00Z"`	Last update timestamp
`tracking_company`	string	`"UPS"`	Shipping carrier name
`tracking_number`	string	`"1Z12345E"`	Package tracking number
`tracking_company_code`	string	`"ups"`	Carrier system code
`line_items`	array[object]	-	Shipped items
`tracking_url`	string	`"https://ups.com/track"`	Tracking page URL
`phone_number`	string	`"+1234567890"`	Contact phone for shipment

Line Items Object

Parameter	Type	Example	Description
`id`	string	`"li_12345"`	Unique line item identifier
`product_id`	string	`"prod_123"`	Associated product ID
`product_title`	string	`"Premium T-Shirt"`	Name of purchased product
`variant_id`	string	`"var_456"`	Product variant ID
`variant_title`	string	`"Blue / Medium"`	Variant description
`quantity`	uint32	`2`	Quantity purchased
`note`	string	`"Gift wrapping requested"`	Product-specific note
`image`	object	-	Product image details
`price`	string	`"29.99"`	Unit price
`compare_at_price`	string	`"39.99"`	Original/compare price
`total_price`	string	`"59.98"`	Total price (price × quantity)
`fulfillment_status`	string	`"fulfilled"`	Fulfillment status
`sku`	string	`"TSHIRT-BL-M"`	Inventory tracking code
`weight`	string	`"0.5"`	Product weight
`weight_unit`	string	`"kg"`	Weight measurement unit
`vendor`	string	`"Fashion Co"`	Product supplier
`product_url`	string	`"https://..."`	Product page URL
`created_at`	string	`"2023-01-01T00:00:00Z"`	Creation time
`updated_at`	string	`"2023-01-01T00:00:00Z"`	Update time
`options`	array[object]	-	Variant options
`product_slug`	string	`"premium-t-shirt"`	Product URL slug
`taxable`	boolean	`true`	Whether item is taxable
`requires_shipping`	boolean	`true`	Whether requires shipping
`spu`	string	`"SPU123"`	Standard Product Unit
`product_tags`	string	`"summer,sale"`	Product tags
`refund_quantity_total`	uint32	`0`	Total refunded quantity
`ship_quantity`	uint32	`2`	Shipped quantity
`custom`	boolean	`false`	Custom product flag
`trunk_price`	string	`"0.00"`	Trunk price
`discount_applications`	string	`"promo10"`	Applied discounts
`tax_price`	string	`"2.99"`	Tax amount
`duty_price`	string	`"0.00"`	Duty cost
`payment_discount_price`	string	`"0.00"`	discount price of the payment

Image Object

Parameter	Type	Example	Description
`src`	string	`"https://..."`	Image URL
`width`	int32	`800`	Image width
`height`	int32	`600`	Image height
`alt`	string	`"Blue T-Shirt"`	Alt text

Options Object

Parameter	Type	Example	Description
`name`	string	`"Color"`	Option name
`value`	string	`"Blue"`	Selected value

Payment Line Object

Parameter	Type	Example	Description
`payment_name`	string	`"VISA-1234"`	Display name of payment method
`payment_channel`	string	`"stripe"`	Payment service provider
`payment_method`	string		Specific payment type
`credit_card_number`	string	`""`	Masked card digits
`trans_channel`	string	`	Transaction channel
`trans_method`	string		Transaction method
`transaction_no`	string	`"txn_789012"`	Unique transaction ID

Shipping Line Object

Parameter	Type	Example	Description
`id`	string	`"ship_12345"`	Unique identifier for the shipping method
`name`	string	`"Express Delivery"`	Display name of the shipping method
`desc`	string	`"2-3 business days"`	Description of shipping terms

Billing Address/ Shipping Address Object

Parameter	Type	Example	Description
`first_name`	string	`"John"`	First name of the billing contact
`last_name`	string	`"Doe"`	Last name of the billing contact
`address`	string	`"1 Rue des Carrieres"`	Primary street address
`address1`	string	`"Suite 1234"`	Additional address line
`phone`	string	`"+861231231234"`	Contact phone number
`city`	string	`"SAN JOSE"`	City name
`zip`	string	`"87036"`	Postal/ZIP code
`province`	string	`"New Mexico"`	State/Province name
`country`	string	`"United States"`	Country name
`company`	string	`"ABC Limited"`	Company name
`latitude`	string	`"22.54"`	Geographic latitude
`longitude`	string	`"114.06"`	Geographic longitude
`name`	string	`"John Doe"`	Full name of billing contact
`country_code`	string	`"US"`	2-letter country code
`province_code`	string	`"NM"`	State/Province code
`phone_area_code`	string	`"+86"`	Phone country code
`email`	string	`"john.doe@example.com"`	Email address
`area`	string	`"Bay area"`	Regional area designation

Primary Market Price Object

Parameter	Type	Example	Description
`compare_at_price`	string	`"129.99"`	Original/list price in primary currency
`price`	string	`"99.99"`	Current selling price in primary currency
`total_price`	string	`"199.98"`	Extended price (price × quantity)
`actual_rate`	string	`"1.12"`	Currency conversion rate applied

Customer Object

Parameter	Type	Example	Description
`id`	string	`"cust_12345"`	Unique customer identifier
`email`	string	`"customer@example.com"`	Customer's email address
`first_name`	string	`"John"`	Customer's first name
`last_name`	string	`"Doe"`	Customer's last name
`phone`	string	`"+1234567890"`	Customer's phone number
`created_at`	string	`"2023-01-01T00:00:00Z"`	Customer account creation date
`updated_at`	string	`"2023-06-01T00:00:00Z"`	Last customer profile update
`order_count`	int32	`5`	Total orders placed by customer
`total_spent`	string	`"499.95"`	Lifetime spending amount

Location Line Object

Parameter	Type	Example	Description
`id`	string	`"1234567890"`	Unique identifier for the location line.
`location_id`	string	`"Doe"`	Identifier for the associated location.
`location_name`	string	`"123 Main St"`	Name of the location, such as a store or warehouse.

Config Object

Parameter	Type	Example	Description
`product_tax_included`	boolean	`true`	Tax inclusion flag
`requires_shipping`	boolean	`true`	Shipping requirement
`checkout_url`	string	`"https://store.com/checkout"`	Order checkout URL

Additional Charge Object

Parameter	Type	Example	Description
`name`	string	`"Gift Wrapping"`	System identifier for charge type
`price`	string	`"5.99"`	Charge amount in order currency
`biz_id`	string	`"gift_wrap_1"`	Business logic identifier
`fee_title`	string	`"Special Packaging"`	Customer-facing charge description

Market Setting Object

Parameter	Type	Example	Description
`primary_market_lang`	string	`"en"`	Primary market language code
`market_lang`	string	`"en-US"`	Localized market language
`market_id`	string		Unique market identifier
`market_currency`	string	`"USD"`	Market currency code
`market_currency_symbol`	object	-	Currency symbol details
`market_base_id`	string	`"base_us"`	Base market ID
`market_base_currency`	string	`"USD"`	Base market currency
`market_base_currency_symbol`	object	-	Base currency symbol
`primary_market_id`	string	`"primary_us"`	Primary market ID
`primary_market_currency`	string	`"USD"`	Primary currency code
`primary_market_currency_symbol`	object	-	Primary currency symbol
`market_price_setting`	object	-	Price calculation settings
`market_country`	string	`"US"`	2-letter country code

Currency Symbol Objects

Parameter	Type	Example	Description
`code`	string	`"USD"`	ISO currency code
`val`	string	`"$"`	Currency symbol
`left`	string	`"$"`	Left-side display
`right`	string	`""`	Right-side display

Market Price Setting Object

Parameter	Type	Example	Description
`local_currency_enabled`	boolean	`true`	Local currency active
`custom_rate_enabled`	boolean	`false`	Custom exchange rate
`custom_rate`	float	`1.0`	Manual exchange rate
`rate`	float	`1.12`	Current exchange rate
`back_rate`	float	`0.89`	Reverse exchange rate
`actual_rate`	float	`1.1198`	Precise exchange rate
`base_to_rate`	float	`1.0`	Base to local rate
`local_to_rate`	float	`1.0`	Local to base rate
`adjust`	int32	`0`	Price adjustment %
`price_round_enabled`	boolean	`true`	Price rounding active

Error Response

Field	Type	Example	Description
`code`	string	`InvalidParameter`	Error http message
`message`	string	``	Error message

200OK