# List all orders

Returns a list of all order objects.

Endpoint: GET /orders
Version: 2018-02-08
Security: APIKeyHeader

## Query parameters:

  - `page` (integer)
    The page number you want to select

  - `results` (integer)
    The number of results to return per page (max 100)

  - `order_status[]` (array)
    Filter orders by order status
    Enum: "UNKNOWN", "AWAITPAY", "PAID", "REFUNDED", "CANCELLED", "PARTIALLY_FULFILLED", "SHIPPED"

  - `shop_app` (string)
    Filter orders by shop app
    Enum: "Amazon", "Bigcommerce", "CSV_Import", "eBay", "ePages", "Etsy", "Godaddy", "Magento", "Shippo", "Shopify", "Spreecommerce", "StripeRelay", "Walmart", "Weebly", "WooCommerce"

  - `start_date` (string)
    Filter orders created after the input date and time (ISO 8601 UTC format).  This is based on the 
placed_at field, meaning when the order has been placed, not when the order object was created.

  - `end_date` (string)
    Filter orders created before the input date and time (ISO 8601 UTC format).  This is based on the 
placed_at field, meaning when the order has been placed, not when the order object was created.

## Header parameters:

  - `SHIPPO-API-VERSION` (string)
    Optional string used to pick a non-default API version to use. See our API version guide.
    Example: "2018-02-08"

## Response 200 fields (application/json):

  - `next` (string)
    Example: "baseurl?page=3&results=10"

  - `previous` (string)
    Example: "baseurl?page=1&results=10"

  - `results` (array)

  - `results.currency` (string)
    Required if total_price is provided
Currency of the total_price and total_tax amounts.
    Example: "USD"

  - `results.notes` (string)
    Custom buyer- or seller-provided notes about the order.
    Example: "This customer is a VIP"

  - `results.order_number` (string)
    An alphanumeric identifier for the order used by the seller/buyer. This identifier doesn't need to be unique.
    Example: "#1068"

  - `results.order_status` (string)
    Current state of the order. See the orders tutorial 
for the logic of how the status is handled.
    Enum: "UNKNOWN", "AWAITPAY", "PAID", "REFUNDED", "CANCELLED", "PARTIALLY_FULFILLED", "SHIPPED"

  - `results.placed_at` (string, required)
    Date and time when the order was placed. This datetime can be different from the datetime of the order object creation on Shippo.
    Example: "2016-09-23T01:28:12Z"

  - `results.shipping_cost` (string)
    Amount paid by the buyer for shipping. This amount can be different from the price the seller will actually pay for shipping.
    Example: "12.83"

  - `results.shipping_cost_currency` (string)
    Required if shipping_cost is provided
Currency of the shipping_cost amount.
    Example: "USD"

  - `results.shipping_method` (string)
    Shipping method (carrier + service or other free text description) chosen by the buyer. 
This value can be different from the shipping method the seller will actually choose.
    Example: "USPS First Class Package"

  - `results.subtotal_price` (string)
    Example: "12.1"

  - `results.total_price` (string)
    Total amount paid by the buyer for this order.
    Example: "24.93"

  - `results.total_tax` (string)
    Total tax amount paid by the buyer for this order.
    Example: "0.0"

  - `results.weight` (string)
    Total weight of the order.
    Example: "0.4"

  - `results.weight_unit` (string)
    The unit used for weight.
    Enum: "g", "kg", "lb", "oz"

  - `results.from_address` (object)
    Address object of the sender / seller. Will be returned expanded by default.

  - `results.from_address.name` (string)
    required for purchase
First and Last Name of the addressee

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Either company or name required; No length validation (first 35 chars printed on label) |
    Example: "Shwan Ippotle"

  - `results.from_address.company` (string)
    Company Name

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Max 35 characters; Either company or name required |
    Example: "Shippo"

  - `results.from_address.street1` (string)
    required for purchase
First street line. Usually street number and street name (except for DHL Germany, see street_no).

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | At least one street line required; Max 35 characters per line |
    Example: "215 Clayton St."

  - `results.from_address.street2` (string)
    Second street line.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | At least one street line required; Max 35 characters per line |

  - `results.from_address.street3` (string)
    Third street line.
Only accepted for USPS international shipments, UPS domestic and UPS international shipments.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | At least one street line required; Max 35 characters per line |

  - `results.from_address.street_no` (string)
    Street number of the addressed building. 
This field can be included in street1 for all carriers except for DHL Germany.

  - `results.from_address.city` (string)
    required for purchase
Name of a city. When creating a Quote Address, sending a city is optional but will yield more accurate Rates.
Please bear in mind that city names may be ambiguous (there are 34 Springfields in the US). Pass in a state
or a ZIP code (see below), if known, it will yield more accurate results.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Required; Max 35 characters |
    Example: "San Francisco"

  - `results.from_address.state` (string)
    required for purchase for some countries
State/Province values are required for shipments from/to the US, AU, and CA. UPS requires province for some
countries (i.e Ireland). To receive more accurate quotes, passing this field is recommended. Most carriers
only accept two or three character state abbreviations.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Required if country requires state; Max 2 characters for US, CA, PR |
    Example: "CA"

  - `results.from_address.zip` (string)
    required for purchase
Postal code of an Address. When creating a Quote Addresses, sending a ZIP is optional but will yield more
accurate Rates.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Max 10 characters |
    Example: "94117"

  - `results.from_address.country` (string, required)
    ISO 3166-1 alpha-2 country codes and country names can be used. For most consistent results, we recommend using country codes like US or DE.
If using country names, please ensure they are spelled correctly and in English. Country names are converted to country codes.
Refer to this guide for a list of country codes.
Sending a country is always required.
    Example: "US"

  - `results.from_address.phone` (string)
    Addresses containing a phone number allow carriers to call the recipient when delivering the Parcel. This
increases the probability of delivery and helps to avoid accessorial charges after a Parcel has been shipped.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Required; Min 1, max 15 characters |
    Example: "+1 555 341 9393"

  - `results.from_address.email` (string)
    E-mail address of the contact person, RFC3696/5321-compliant.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Max 80 characters |
    Example: "shippotle@shippo.com"

  - `results.from_address.is_residential` (boolean)
    Example: true

  - `results.from_address.metadata` (string)
    A string of up to 100 characters that can be filled with any additional information you want 
to attach to the object.
    Example: "Customer ID 123456"

  - `results.from_address.is_complete` (boolean)
    Complete addresses contain all required values.Incomplete addresses have failed one or multiple 
validations.Incomplete Addresses are eligible for requesting rates but lack at least one required 
value for purchasing labels.
    Example: true

  - `results.from_address.latitude` (number,string)
    Latitude of address

  - `results.from_address.longitude` (number,string)
    Longitude of address

  - `results.from_address.object_created` (string)
    Date and time of Address creation.
    Example: "2014-07-09T02:19:13.174Z"

  - `results.from_address.object_id` (string)
    Unique identifier of the given Address object. 
This ID is required to create a Shipment object.
    Example: "d799c2679e644279b59fe661ac8fa488"

  - `results.from_address.object_owner` (string)
    Username of the user who created the Address object.
    Example: "shippotle@shippo.com"

  - `results.from_address.object_updated` (string)
    Date and time of last Address update. Since you cannot update Addresses after they were created, this time 
stamp reflects the time when the Address was changed by Shippo's systems for the last time, e.g., during the 
approximation of one or more values.
    Example: "2014-07-09T02:19:13.174Z"

  - `results.from_address.validation_results` (object)
    Object that contains information regarding if an address had been validated or not. Also contains any messages 
generated during validation. Children keys are is_valid(boolean) and messages(array).

  - `results.from_address.validation_results.is_valid` (boolean)

  - `results.from_address.validation_results.messages` (array)

  - `results.from_address.validation_results.messages.code` (string)
    See Address Validation Codes
    Example: "Unknown Street"

  - `results.from_address.validation_results.messages.source` (string)
    See Address Validation Source
    Example: "Shippo Address Validator"

  - `results.from_address.validation_results.messages.text` (string)
    Example: "City, State and ZIP Code are valid, but street address is not a match."

  - `results.from_address.validation_results.messages.type` (string)
    Example: "address_warning"

  - `results.from_address.test` (boolean)
    Indicates whether the object has been created in test mode.

  - `results.to_address` (object, required)
    Address object of the recipient / buyer. Will be returned expanded by default.

  - `results.line_items` (array)
    Array of line item objects representing the items in this order. 
All objects will be returned expanded by default.

  - `results.line_items.currency` (string)
    Currency of the total_price amount.
    Example: "USD"

  - `results.line_items.manufacture_country` (string)
    Country the item was manufactured in. In the Shippo dashboard, this value will be used ot pre-fill the customs declaration when creating a label for this order.
    Example: "US"

  - `results.line_items.max_delivery_time` (string)
    The date and time this item needs to be delivered by, i.e. by when the carrier delivers it to the buyer. 
This value is used by some platforms such as eBay to measure a seller's shipping time and performance. 
It will be displayed in the Shippo dashboard.
    Example: "2016-07-23T00:00:00Z"

  - `results.line_items.max_ship_time` (string)
    The date and time this item needs to be fulfilled by, i.e. by when the shipping label needs to be 
created and handed over to the carrier. This value is used by some platforms such as eBay to measure 
a seller's handling time and performance. It will be displayed in the Shippo dashboard.
    Example: "2016-07-23T00:00:00Z"

  - `results.line_items.quantity` (integer)
    The quantity of this item in this order.
    Example: 20

  - `results.line_items.sku` (string)
    The stock keeping unit value of this item.
    Example: "HM-123"

  - `results.line_items.title` (string)
    Title of the line item.
    Example: "Hippo Magazines"

  - `results.line_items.total_price` (string)
    Total price paid by the buyer for this item (or these items, if quantity > 1).
    Example: "12.1"

  - `results.line_items.variant_title` (string)
    A variant is a specific variation of an item (e.g. size M or color blue). 
Variants might be exposed as a separate resource in the future too. 
Currently the variant title is a free text field describing the variant.
    Example: "June Edition"

  - `results.line_items.weight` (string)
    Total weight of this/these item(s). Instead of specifying the weight of all items, 
you can also set the total_weight value of the order object.
    Example: "0.4"

  - `results.line_items.object_id` (string)
    Unique identifier of the line item object.
    Example: "abf7d5675d744b6ea9fdb6f796b28f28"

  - `results.object_id` (string)
    Unique identifier of the order object.
    Example: "adcfdddf8ec64b84ad22772bce3ea37a"

  - `results.object_owner` (string)
    Username of the user who created the object.
    Example: "shippotle@shippo.com"

  - `results.shop_app` (string)
    Platform the order was created on and, if applicable, imported from. 
Orders created via the Shippo API or dashboard will have the value "Shippo".
    Enum: "Amazon", "Bigcommerce", "CSV_Import", "eBay", "ePages", "Etsy", "Godaddy", "Magento", "Shippo", "Shopify", "Spreecommerce", "StripeRelay", "Walmart", "Weebly", "WooCommerce"

  - `results.transactions` (array)
    Array of transaction objects representing all shipping labels purchased for this order.
All objects are returned expanded with a limited number of fields by default.