# List orders

Obtains a list of orders that match the specified criteria. All filters are optional. If no filters are provided, recent orders will be returned.

Endpoint: GET /orders
Version: 1.0.0
Security: basicAuth

## Query parameters:

  - `customerName` (string)
    Returns orders that match the specified customer name

  - `itemKeyword` (string)
    Returns orders containing items matching the specified keyword. Fields searched are Sku, Description, and Options.

  - `createDateStart` (string)
    Returns orders created in ShipStation after the specified date

  - `createDateEnd` (string)
    Returns orders created in ShipStation before the specified date

  - `modifyDateStart` (string)
    Returns orders modified after the specified date

  - `modifyDateEnd` (string)
    Returns orders modified before the specified date

  - `orderDateStart` (string)
    Returns orders greater than the specified date

  - `orderDateEnd` (string)
    Returns orders less than or equal to the specified date

  - `orderNumber` (string)
    Filter by order number (performs a "starts with" search)

  - `orderStatus` (string)
    Filter by order status
    Enum: "awaiting_payment", "awaiting_shipment", "pending_fulfillment", "shipped", "on_hold", "cancelled", "rejected_fulfillment"

  - `paymentDateStart` (string)
    Returns orders paid after the specified date

  - `paymentDateEnd` (string)
    Returns orders paid before the specified date

  - `storeId` (integer)
    Filter orders to a single store

  - `sortBy` (string)
    Field to sort results by
    Enum: "OrderDate", "ModifyDate", "CreateDate"

  - `sortDir` (string)
    Sort direction
    Enum: "ASC", "DESC"

  - `page` (integer)
    Page number

  - `pageSize` (integer)
    Number of results per page. Maximum 500.

## Response 200 fields (application/json):

  - `orders` (array)

  - `orders.orderId` (integer)
    System-generated identifier for the order
    Example: 93348442

  - `orders.orderNumber` (string)
    User-defined order number
    Example: "TEST-ORDER-API-DOCS"

  - `orders.orderKey` (string)
    Unique key for the order
    Example: "0f6bec18-3e89-4771-83aa-f392d84f4c74"

  - `orders.orderDate` (string)
    Date the order was placed
    Example: "2015-06-29T08:46:27Z"

  - `orders.createDate` (string)
    Timestamp when order was created in ShipStation
    Example: "2016-01-12T16:03:06Z"

  - `orders.modifyDate` (string)
    Timestamp when order was last modified
    Example: "2016-01-12T16:03:06Z"

  - `orders.paymentDate` (any)
    Date the order was paid
    Example: "2015-06-29T08:46:27Z"

  - `orders.shipByDate` (any)
    Date the order should be shipped by
    Example: "2015-07-05T00:00:00Z"

  - `orders.orderStatus` (string)
    Current status of the order
    Enum: "awaiting_payment", "awaiting_shipment", "pending_fulfillment", "shipped", "on_hold", "cancelled", "rejected_fulfillment"

  - `orders.customerId` (integer)
    Unique identifier for the customer
    Example: 37701499

  - `orders.customerUsername` (string)
    Customer username or identifier
    Example: "headhoncho@whitehouse.gov"

  - `orders.customerEmail` (string)
    Customer email address
    Example: "headhoncho@whitehouse.gov"

  - `orders.billTo` (object)
    Physical address for shipping or billing

  - `orders.billTo.name` (string)
    Name of the recipient
    Example: "John Doe"

  - `orders.billTo.company` (any)
    Company name
    Example: "Acme Corp"

  - `orders.billTo.street1` (string)
    First line of the street address
    Example: "123 Main St"

  - `orders.billTo.street2` (any)
    Second line of the street address
    Example: "Apt 4B"

  - `orders.billTo.street3` (any)
    Third line of the street address
    Example: "Building B"

  - `orders.billTo.city` (string)
    City name
    Example: "Austin"

  - `orders.billTo.state` (string)
    State or province code
    Example: "TX"

  - `orders.billTo.postalCode` (string)
    Postal or ZIP code
    Example: "78701"

  - `orders.billTo.country` (string)
    Two-letter ISO country code
    Example: "US"

  - `orders.billTo.phone` (any)
    Phone number
    Example: "512-555-1234"

  - `orders.billTo.residential` (any)
    Whether the address is residential
    Example: true

  - `orders.billTo.addressVerified` (any)
    Address verification status
    Example: "Address validated successfully"

  - `orders.shipTo` (object)
    Physical address for shipping or billing

  - `orders.items` (array)
    Array of order items

  - `orders.items.orderItemId` (integer)
    System-generated order item ID
    Example: 128836912

  - `orders.items.lineItemKey` (any)
    External line item key
    Example: "vd08-MSLbtx"

  - `orders.items.sku` (string)
    Product SKU
    Example: "ABC123"

  - `orders.items.name` (string)
    Item name
    Example: "Test item #1"

  - `orders.items.imageUrl` (any)
    Item image URL
    Example: "https://example.com/images/product.jpg"

  - `orders.items.weight` (object)
    Weight measurement

  - `orders.items.weight.value` (number, required)
    Weight value
    Example: 24

  - `orders.items.weight.units` (string, required)
    Weight unit of measurement
    Enum: "pounds", "ounces", "grams"

  - `orders.items.quantity` (integer)
    Quantity
    Example: 2

  - `orders.items.unitPrice` (number)
    Unit price
    Example: 99.99

  - `orders.items.taxAmount` (any)
    Tax amount
    Example: 2.5

  - `orders.items.shippingAmount` (any)
    Shipping amount
    Example: 5

  - `orders.items.warehouseLocation` (any)
    Warehouse location
    Example: "Aisle 1, Bin 7"

  - `orders.items.options` (array)
    Item options

  - `orders.items.options.name` (string)
    Option name
    Example: "Size"

  - `orders.items.options.value` (string)
    Option value
    Example: "Large"

  - `orders.items.productId` (any)
    Product ID
    Example: 7239919

  - `orders.items.fulfillmentSku` (any)
    Fulfillment SKU
    Example: "SKU-Fulfilled"

  - `orders.items.adjustment` (boolean)
    Whether this is an adjustment item

  - `orders.items.upc` (any)
    UPC code
    Example: "32-65-98"

  - `orders.items.createDate` (string)
    Creation timestamp

  - `orders.items.modifyDate` (string)
    Last modification timestamp

  - `orders.orderTotal` (number)
    Total order amount
    Example: 194.43

  - `orders.amountPaid` (number)
    Amount paid by customer
    Example: 218.73

  - `orders.taxAmount` (number)
    Total tax amount
    Example: 5

  - `orders.shippingAmount` (number)
    Shipping amount
    Example: 10

  - `orders.customerNotes` (any)
    Notes from the customer
    Example: "Please ship as soon as possible!"

  - `orders.internalNotes` (any)
    Internal notes (not visible to customer)
    Example: "Customer called and would like to upgrade shipping"

  - `orders.gift` (boolean)
    Whether this is a gift order

  - `orders.giftMessage` (any)
    Gift message
    Example: "Happy Birthday!"

  - `orders.paymentMethod` (any)
    Payment method used
    Example: "Credit Card"

  - `orders.requestedShippingService` (any)
    Shipping service requested by customer
    Example: "Priority Mail"

  - `orders.carrierCode` (any)
    Carrier code
    Example: "fedex"

  - `orders.serviceCode` (any)
    Service code
    Example: "fedex_2day"

  - `orders.packageCode` (any)
    Package type code
    Example: "package"

  - `orders.confirmation` (string)
    Delivery confirmation type
    Enum: "none", "delivery", "signature", "adult_signature", "direct_signature"

  - `orders.shipDate` (any)
    Date the order was shipped
    Example: "2015-07-02"

  - `orders.holdUntilDate` (any)
    Date to hold order until
    Example: "2015-07-05"

  - `orders.weight` (object)
    Weight measurement

  - `orders.dimensions` (any)

  - `orders.insuranceOptions` (object)
    Shipping insurance options

  - `orders.insuranceOptions.provider` (any)
    Insurance provider
    Enum: "none", "carrier", "xcover", "parcelguard", "shipsurance"

  - `orders.insuranceOptions.insureShipment` (boolean)
    Whether to insure the shipment
    Example: true

  - `orders.insuranceOptions.insuredValue` (number)
    Insured value amount
    Example: 200

  - `orders.internationalOptions` (object)
    International shipping options

  - `orders.internationalOptions.contents` (any)
    Type of contents
    Enum: "merchandise", "documents", "gift", "returned_goods", "sample"

  - `orders.internationalOptions.customsItems` (array)
    Array of customs items

  - `orders.internationalOptions.nonDelivery` (any)
    Action to take if delivery fails
    Enum: "return_to_sender", "treat_as_abandoned"

  - `orders.advancedOptions` (object)
    Advanced shipping options

  - `orders.advancedOptions.warehouseId` (any)
    Warehouse ID
    Example: 98765

  - `orders.advancedOptions.nonMachinable` (boolean)
    Whether the package is non-machinable

  - `orders.advancedOptions.saturdayDelivery` (boolean)
    Whether to deliver on Saturday

  - `orders.advancedOptions.containsAlcohol` (boolean)
    Whether the package contains alcohol

  - `orders.advancedOptions.mergedOrSplit` (boolean)
    Whether this is a merged or split order

  - `orders.advancedOptions.mergedIds` (array)
    Array of merged order IDs

  - `orders.advancedOptions.parentId` (any)
    Parent order ID for split orders
    Example: 93348442

  - `orders.advancedOptions.storeId` (any)
    Store ID
    Example: 12345

  - `orders.advancedOptions.customField1` (any)
    Custom field 1
    Example: "Custom data that you can add to an order"

  - `orders.advancedOptions.customField2` (any)
    Custom field 2
    Example: "Per UI settings, this can appear on some carrier labels"

  - `orders.advancedOptions.customField3` (any)
    Custom field 3
    Example: "https://help.shipstation.com/hc/en-us/articles/206639957"

  - `orders.advancedOptions.source` (any)
    Order source
    Example: "Webstore"

  - `orders.advancedOptions.billToParty` (any)
    Bill to party
    Example: "third_party"

  - `orders.advancedOptions.billToAccount` (any)
    Bill to account
    Example: "123456789"

  - `orders.advancedOptions.billToPostalCode` (any)
    Bill to postal code
    Example: "78701"

  - `orders.advancedOptions.billToCountryCode` (any)
    Bill to country code
    Example: "US"

  - `orders.advancedOptions.movementIndicator` (any)
    An indicator that will tell the carrier the type of movement for the shipment.
    Example: "b2c"

  - `orders.tagIds` (array)
    Array of tag IDs associated with this order

  - `orders.userId` (any)
    User assigned to order (GUID format)
    Example: "123456AB-ab12-3c4d-5e67-89f1abc1defa"

  - `orders.externallyFulfilled` (boolean)
    Whether order is externally fulfilled

  - `orders.externallyFulfilledBy` (any)
    External fulfillment provider name
    Example: "Amazon FBA"

  - `total` (integer)
    Total number of orders matching criteria
    Example: 2

  - `page` (integer)
    Current page number
    Example: 1

  - `pages` (integer)
    Total number of pages
    Example: 1

## Response 400 fields (application/json):

  - `message` (string)
    Example: "Invalid request parameters"

## Response 401 fields (application/json):

  - `message` (string)
    Example: "Invalid API credentials"

## Response 500 fields (application/json):

  - `message` (string)
    Example: "An internal error occurred"