> For the complete documentation index, see [llms.txt](https://help.orderdesk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.orderdesk.com/api-documentation/v2-api-reference/orders/get-multiple-orders.md).

# Get Multiple Orders

Returns orders matching the supplied filters, sorted by date added in descending order by default. With no filters, the 50 most recent orders are returned.

To search for a specific order, filter your request with the query string fields below. Filters are combined with AND, so passing both `source_name` and `folder_id` returns only the orders matching both.

The `limit` parameter defaults to 50 and has a maximum of 500. Values above 500 are reduced to 500 rather than rejected, so compare `records_returned` with the value you requested. Use `offset` to retrieve further pages, and `total_records` to determine how many records remain.

```json
{"openapi":"3.0.3","info":{"title":"Order Desk API","version":"2.0"},"tags":[{"name":"Orders"}],"servers":[{"url":"https://app.orderdesk.me/api/v2","description":"Production"}],"security":[{"OrderDeskStoreId":[],"OrderDeskApiKey":[]}],"components":{"securitySchemes":{"OrderDeskStoreId":{"type":"apiKey","in":"header","name":"ORDERDESK-STORE-ID","description":"Your store ID, found under Store Settings on the API tab."}},"parameters":{"FolderIdFilter":{"name":"folder_id","in":"query","description":"Search for orders from a particular folder. For multiple folders, enter multiple IDs\nseparated by a comma, such as `1004,1009,1010`. See the Folders guide.\n","schema":{"type":"string"}},"Limit":{"name":"limit","in":"query","description":"How many records to return. Defaults to 50, with a maximum of 500. Values above 500 are\nreduced to 500 rather than rejected.\n","schema":{"type":"integer","default":50,"minimum":1,"maximum":500}},"Offset":{"name":"offset","in":"query","description":"The number of records to offset.","schema":{"type":"integer","default":0,"minimum":0}}},"schemas":{"DateTime":{"type":"string","description":"Date and time in `YYYY-MM-DD HH:MM:SS` format. UTC unless otherwise stated."},"PaginatedEnvelope":{"allOf":[{"$ref":"#/components/schemas/ResponseEnvelope"},{"type":"object","properties":{"total_records":{"type":"integer","description":"Total number of records matching the filters, regardless of paging."},"records_returned":{"type":"integer","description":"Number of records returned in this response."},"offset":{"type":"integer","description":"The offset applied to this request."},"limit":{"type":"integer","description":"The limit applied to this request, after any reduction to the maximum.\n"}}}]},"ResponseEnvelope":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["success","error"],"description":"Either `success` or `error`."},"message":{"type":"string","description":"Describes the result. Always present when an error occurs."},"execution_time":{"type":"string","description":"Time taken to process the request."}}},"Order":{"description":"An order as stored in Order Desk. It contains the customer and shipping addresses, the line\nitems, the order totals, the payment details, and any shipments recorded against it.\n\nOrder Desk assigns each order an internal `id`. Your own identifier is stored in `source_id`,\nand the system the order came from is stored in `source_name`. Every path that takes an\n`order_id` refers to the Order Desk `id`. To retrieve an order by your own identifier, search\non `source_id` instead.\n\nThe `quantity_total`, `weight_total`, `product_total`, `discount_total`, and `order_total`\nfields are calculated from the line items and cannot be set directly.\n","allOf":[{"type":"object","properties":{"id":{"type":"string","readOnly":true,"description":"Order Desk's internal ID number. Returned as a string, even though it is\nalways numeric. Read-only.\n"}}},{"$ref":"#/components/schemas/OrderFields"},{"type":"object","properties":{"cc_number_masked":{"type":"string","readOnly":true,"description":"Obfuscated credit card number. This is the field returned in responses. Use\n`cc_number` when writing.\n"},"quantity_total":{"type":"integer","readOnly":true,"description":"Total number of all items in the order. Read-only."},"weight_total":{"type":"number","format":"double","readOnly":true,"description":"Total weight of all items in the order. Read-only."},"product_total":{"type":"number","format":"double","readOnly":true,"description":"Total price of all items in the order. Read-only."},"discount_total":{"type":"number","format":"double","readOnly":true,"description":"Total value of all discounts, stored as a positive number. Read-only."},"order_total":{"type":"number","format":"double","readOnly":true,"description":"Calculated price of the entire order. Read-only."},"email_count":{"type":"string","readOnly":true,"description":"Number of orders matching this email address. Returned as a string, even\nthough it is always numeric. Read-only.\n"},"previous_folder_id":{"type":"string","readOnly":true,"description":"The folder the order was in before its most recent move. Returned as a\nstring. Read-only.\n"},"tag_color":{"type":"string","readOnly":true,"description":"Not in use."},"tag_name":{"type":"string","readOnly":true,"description":"Not in use."},"order_items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItem"}},"order_shipments":{"type":"array","readOnly":true,"description":"List of shipments recorded against this order. These may not be modified through\nthe order object.\n","items":{"$ref":"#/components/schemas/Shipment"}},"order_history":{"type":"array","readOnly":true,"description":"Returned when `get_order_history` is set to 1 on a search, and after an order\nhistory entry is added.\n","items":{"$ref":"#/components/schemas/OrderHistoryEntry"}}}}]},"OrderFields":{"type":"object","description":"Order fields common to both reads and writes.","properties":{"source_id":{"type":"string","description":"Your original order ID. If blank, Order Desk's internal ID will be used."},"source_name":{"type":"string","default":"Order Desk","description":"Name of the order source, cart, or marketplace. If the source is not recognized or\nis not entered, this defaults to `Order Desk`.\n"},"email":{"type":"string","format":"email"},"shipping_method":{"type":"string","description":"Name of the selected shipping method."},"shipping_total":{"type":"number","format":"double"},"handling_total":{"type":"number","format":"double"},"tax_total":{"type":"number","format":"double"},"cc_exp":{"type":"string","pattern":"^\\d{2}/\\d{4}$","description":"Credit card expiration in `MM/YYYY` format."},"processor_response":{"type":"string","description":"Gateway transaction ID in `<gateway_name>: <transaction_id>` format."},"payment_type":{"type":"string","description":"Visa, MasterCard, PayPal, etc."},"payment_status":{"$ref":"#/components/schemas/PaymentStatus"},"processor_balance":{"type":"number","format":"double","description":"Amount charged at the processor. This is decremented when refunds are made, and\ndefaults to `order_total`.\n"},"refund_total":{"type":"number","format":"double","description":"Amount refunded on the order from within Order Desk."},"customer_id":{"type":"string","description":"Customer ID from the originating system."},"ip_address":{"type":"string","description":"Customer's IP address."},"fulfillment_name":{"type":"string","description":"Once the order has been sent for fulfillment, the fulfillment method name is entered here."},"fulfillment_id":{"type":"string","description":"Internal ID of the fulfillment service, when available."},"folder_id":{"type":"integer","description":"ID of the folder containing the order. New orders default to the first folder when\nthis is omitted. Omitting it on an update leaves the order in its current folder.\nSee the Folders guide.\n"},"date_added":{"allOf":[{"$ref":"#/components/schemas/DateTime"}],"description":"Order date stored in UTC."},"date_updated":{"allOf":[{"$ref":"#/components/schemas/DateTime"}],"description":"Date the order was last updated, stored in UTC."},"checkout_data":{"allOf":[{"$ref":"#/components/schemas/KeyValue"}],"description":"Collection of extra order details in key/value format. Used when the details may\nneed to be manually edited in Order Desk. Maximum total size is 3,500 characters\nwhen JSON-encoded.\n"},"order_metadata":{"allOf":[{"$ref":"#/components/schemas/KeyValue"}],"description":"Collection of extra (hidden) order details in key/value format. Maximum total size\nis 2,000 characters when JSON-encoded.\n"},"shipping":{"allOf":[{"$ref":"#/components/schemas/Address"}],"description":"Shipping address details. If nothing is entered, the customer address will be copied\nhere.\n"},"customer":{"allOf":[{"$ref":"#/components/schemas/Address"}],"description":"Customer address details. If nothing is entered, the shipping address will be copied\nhere.\n"},"return_address":{"$ref":"#/components/schemas/ReturnAddress"},"discount_list":{"type":"array","description":"List of discounts applied to the order.","items":{"$ref":"#/components/schemas/Discount"}},"order_notes":{"type":"array","description":"List of notes on the order.","items":{"$ref":"#/components/schemas/OrderNote"}}}},"PaymentStatus":{"type":"string","default":"Captured","description":"Current payment status for the order. Defaults to `Captured`.","enum":["Approved","Authorized","Captured","Fully Refunded","Partially Refunded","Pending","Rejected","Voided"]},"KeyValue":{"type":"object","additionalProperties":true,"description":"A collection in key/value format. Must be flat, with no nested arrays. Keys must be\nstrings, and values must be strings, numbers, booleans, or null.\n\nWhen the collection is empty, the API returns an empty array (`[]`) rather than an\nempty object. Treat both as \"no entries\" when parsing.\n"},"Address":{"type":"object","description":"Customer or shipping address details. A first and last name combination or a company\nname must be entered to be a valid order.\n","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"address3":{"type":"string","description":"Street address 3. Not available for customer addresses."},"address4":{"type":"string","description":"Street address 3. Not available for customer addresses."},"city":{"type":"string"},"state":{"type":"string","description":"State or region."},"postal_code":{"type":"string","description":"ZIP or postal code."},"country":{"type":"string","description":"Country code or full country name."},"phone":{"type":"string"}}},"ReturnAddress":{"type":"object","description":"If an order has a custom return address, it is entered here. This can be set by a rule,\nor when the order is inserted through the API.\n","properties":{"title":{"type":"string","description":"Return address title."},"name":{"type":"string","description":"Shipping name."},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string","description":"State or region."},"postal_code":{"type":"string"},"country":{"type":"string","description":"Country code or full country name."},"phone":{"type":"string"}}},"Discount":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string","description":"Code used for the discount. Optional."},"amount":{"type":"number","format":"double","description":"The discount amount. Discounts should be stored as positive numbers."}}},"OrderNote":{"type":"object","description":"There is a 2,000 character max for all notes, including date and username metadata, so\nkeep note content under 1,800 characters to avoid data loss.\n","properties":{"date_added":{"$ref":"#/components/schemas/DateTime"},"username":{"type":"string","description":"Name of the person who wrote the note."},"content":{"type":"string","maxLength":1800}}},"OrderItem":{"description":"A product contained in an order. Items can be modified one at a time, or through the order\nitself: passing an `order_items` array to the order update operation will add items that have\nno `id`, update items that do, and remove any item that is omitted.\n\nModifying items recalculates the order totals.\n","allOf":[{"type":"object","properties":{"id":{"type":"integer","readOnly":true,"description":"Order Desk's internal ID number for the order item. Read-only."}}},{"$ref":"#/components/schemas/OrderItemFields"}]},"OrderItemFields":{"type":"object","properties":{"name":{"type":"string"},"price":{"type":"number","format":"double","default":0},"quantity":{"type":"integer","default":1},"weight":{"type":"number","format":"double"},"code":{"type":"string","description":"Item SKU or product code."},"delivery_type":{"$ref":"#/components/schemas/DeliveryType"},"category_code":{"type":"string","description":"Further details about the type of item. Freeform text."},"fulfillment_method":{"type":"string","description":"Fulfillment method responsible for this item, when one applies."},"variation_list":{"allOf":[{"$ref":"#/components/schemas/KeyValue"}],"description":"Collection of variations in key/value format, such as `{\"Size\": \"Large\", \"Color\":\n\"Red\"}`. Maximum total size is 5,000 characters when JSON-encoded.\n"},"metadata":{"allOf":[{"$ref":"#/components/schemas/KeyValue"}],"description":"Collection of extra (hidden) item details in key/value format. Maximum total size is\n15,000 characters when JSON-encoded.\n"}}},"DeliveryType":{"type":"string","default":"ship","description":"Available options are `ship`, `noship`, `download`, or `future`. Defaults to `ship`.\n","enum":["ship","noship","download","future"]},"Shipment":{"description":"A record that some or all of an order has left the warehouse, along with the carrier and\ntracking number used. An order can contain multiple shipments, which is how a partial\nfulfillment is represented.\n\nShipments may not be modified through the order object.\n","allOf":[{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"order_id":{"type":"integer","readOnly":true},"store_id":{"type":"integer","readOnly":true}}},{"$ref":"#/components/schemas/ShipmentFields"},{"type":"object","properties":{"label_format":{"type":"string","readOnly":true,"description":"Format of the stored label, when one exists."},"label_image":{"type":"string","readOnly":true,"description":"Stored shipping label, when one exists."},"print_status":{"type":"string","readOnly":true,"description":"Whether the label has been printed."},"cart_shipment_id":{"type":"string","readOnly":true,"description":"Shipment ID in the originating cart, when known."},"label_shipment_id":{"type":"string","readOnly":true,"description":"Shipment ID at the label provider, when known."},"order_items":{"type":"array","readOnly":true,"description":"The order items covered by this shipment.","items":{"type":"object","additionalProperties":true}},"date_shipped":{"allOf":[{"$ref":"#/components/schemas/DateTime"}],"readOnly":true},"date_added":{"allOf":[{"$ref":"#/components/schemas/DateTime"}],"readOnly":true}}}]},"ShipmentFields":{"type":"object","properties":{"tracking_number":{"type":"string","description":"Carrier-assigned tracking number. Use `n/a` if no tracking number is applicable.\n"},"carrier_code":{"type":"string","description":"Carrier code such as `USPS` or `FedEx`, when available."},"shipment_method":{"type":"string","description":"Shipping service name, such as `First Class International`."},"weight":{"type":"number","format":"double","description":"Final shipment weight."},"cost":{"type":"number","format":"double","description":"Your cost to send the shipment."},"status":{"type":"string","description":"Current shipment status, used by the EasyPost webhook."},"tracking_url":{"type":"string","description":"If omitted, Order Desk attempts to determine it from the tracking number format and\ncarrier code.\n"}}},"OrderHistoryEntry":{"type":"object","description":"An entry in the order's history. History is append-only, and an order holds a maximum of\n250 entries.\n","properties":{"source_name":{"type":"string","description":"What wrote this entry."},"note":{"type":"string"},"date_added":{"$ref":"#/components/schemas/DateTime"}}}},"responses":{"BadRequest":{"description":"The request was rejected. `message` names the problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEnvelope"}}}},"Unauthorized":{"description":"Authentication failed. See the Authentication guide, and\nnote that an invalid store ID blocks your store rather than simply\nfailing the request.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEnvelope"}}}},"RateLimited":{"description":"You are sending too fast. Wait `X-Retry-After` seconds. See\nthe Rate Limits guide.\n","headers":{"X-Tokens-Remaining":{"description":"Number of request tokens currently available.","schema":{"type":"integer"}},"X-Retry-After":{"description":"Seconds to wait before requests can resume.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEnvelope"}}}},"Error":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseEnvelope"}}}}}},"paths":{"/orders":{"get":{"tags":["Orders"],"summary":"Get Multiple Orders","description":"Returns orders matching the supplied filters, sorted by date added in descending\norder by default. With no filters, the 50 most recent orders are returned.\n\nTo search for a specific order, filter your request with the query string fields\nbelow. Filters are combined with AND, so passing both `source_name` and\n`folder_id` returns only the orders matching both.\n\nThe `limit` parameter defaults to 50 and has a maximum of 500. Values above 500\nare reduced to 500 rather than rejected, so compare `records_returned` with the\nvalue you requested. Use `offset` to retrieve further pages, and `total_records`\nto determine how many records remain.\n","operationId":"listOrders","parameters":[{"$ref":"#/components/parameters/FolderIdFilter"},{"name":"folder_name","in":"query","description":"Search for orders from a particular folder. Enter the folder's exact name instead of\nits ID.\n","schema":{"type":"string"}},{"name":"source_id","in":"query","description":"Your original order ID from the originating cart or marketplace.","schema":{"type":"string"}},{"name":"source_name","in":"query","description":"The name of the order source.","schema":{"type":"string"}},{"name":"search_start_date","in":"query","description":"Start date from when an order was added. Search in UTC time.","schema":{"$ref":"#/components/schemas/DateTime"}},{"name":"search_end_date","in":"query","description":"End date from when an order was added. Search in UTC time.","schema":{"$ref":"#/components/schemas/DateTime"}},{"name":"search_start_date_local","in":"query","description":"Start date from when an order was added. Search in local store time.","schema":{"$ref":"#/components/schemas/DateTime"}},{"name":"search_end_date_local","in":"query","description":"End date from when an order was added. Search in local store time.","schema":{"$ref":"#/components/schemas/DateTime"}},{"name":"modified_start_date","in":"query","description":"Start date from when an order was modified. Search in UTC time.","schema":{"$ref":"#/components/schemas/DateTime"}},{"name":"modified_end_date","in":"query","description":"End date from when an order was modified. Search in UTC time.","schema":{"$ref":"#/components/schemas/DateTime"}},{"name":"email","in":"query","description":"Search for orders with a particular email address.","schema":{"type":"string","format":"email"}},{"name":"customer_id","in":"query","description":"Search for orders with a particular customer ID.","schema":{"type":"string"}},{"name":"customer_first_name","in":"query","description":"Search the customer first name field.","schema":{"type":"string"}},{"name":"customer_last_name","in":"query","description":"Search the customer last name field.","schema":{"type":"string"}},{"name":"customer_company","in":"query","description":"Search the customer company field.","schema":{"type":"string"}},{"name":"customer_address1","in":"query","description":"Search the customer address1 field.","schema":{"type":"string"}},{"name":"customer_phone","in":"query","description":"Search the customer phone field.","schema":{"type":"string"}},{"name":"shipping_first_name","in":"query","description":"Search the shipping first name field.","schema":{"type":"string"}},{"name":"shipping_last_name","in":"query","description":"Search the shipping last name field.","schema":{"type":"string"}},{"name":"shipping_company","in":"query","description":"Search the shipping company field.","schema":{"type":"string"}},{"name":"shipping_address1","in":"query","description":"Search the shipping address1 field.","schema":{"type":"string"}},{"name":"shipping_phone","in":"query","description":"Search the shipping phone field.","schema":{"type":"string"}},{"name":"get_order_history","in":"query","description":"Set this to 1 to include order history. This slows down the results considerably, so\nuse it carefully.\n","schema":{"type":"integer","enum":[0,1],"default":0}},{"name":"order_by","in":"query","description":"Order the query by an order field. Defaults to `date_added`. An invalid value\nreturns a `400` response.\n","schema":{"type":"string","default":"date_added"}},{"name":"order","in":"query","description":"Sort direction. Defaults to `DESC`.","schema":{"type":"string","enum":["ASC","DESC"],"default":"DESC"}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Matching orders, or an empty `orders` array if nothing matched.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedEnvelope"},{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"default":{"$ref":"#/components/responses/Error"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.orderdesk.com/api-documentation/v2-api-reference/orders/get-multiple-orders.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.