OrderCriteria

Overview

The OrderCriteria object contains parameters you can use to query order data.

Note: If retrieving orders with bundles, "Complete" does not contain the component SKUs of a bundle.

  • Send DetailLevel of "High" to retrieve Bundle SKU data.
  • The response will breakout both Bundle SKU and all component SKUs under the LineItemType property.
    • The Bundle SKU will not be identified uniquely as a bundle SKU to differentiate from the component SKUs.
  • Alternately, you can make a call to GetOrderFulfillmentDetailList where the response will only include the bundle item SKUs, and not the bundle SKU on the order.

Fields

Field Name

Data Type

Description

OrderCreationFilterBeginTimeGMT

DateTime

Only return orders created on or after this timestamp. This should be paired with an end time.

OrderCreationFilterEndTimeGMT

DateTime

Only return orders created on or before this timestamp. This should be paired with a beginning time.

StatusUpdateFilterBeginTimeGMT

DateTime

Only return orders whose status was last set after this timestamp. This should be paired with an end time.

StatusUpdateFilterEndTimeGMT

DateTime

Only return orders whose status was last set before this date and time. This should be paired with a beginning time.

JoinDateFiltersWithOr

boolean

The default behavior of the date filters is to only return orders which satisfy both date ranges. Set this boolean to true to return orders which satisfy either of the date ranges. A submitted value of false maintains the default behavior.

DetailLevel

DetailLevelType

This value controls how much data is returned by the method. The value chosen here will affect the maximum PageSize for the request.  See below for more detail. It is strongly encouraged to use the lowest acceptable detail level required to retrieve the necessary data. Acceptable Values:

ExportState

ExportStateType

Only return orders matching the given export state. Acceptable Values:

  • Unknown - Get orders in any export state.
  • NotExported - Get orders not yet marked exported through the API.
  • Exported - Get orders already marked exported through the API.

OrderIDList

int[]

Only return orders matching this list of Order IDs

ClientOrderIdentifierList

string[]

Only return orders matching this list of Client Order Identifiers. If both OrderIDList and ClientOrderIdentifierList are submitted, the response will contain the union of the two lists.

OrderStateFilter

OrderStateCode

Enumerated value. Acceptable Values:

  • Active - All orders that are not archived. Check OrderState in the returned order to see if it is a canceled order.
  • Archived - All orders that are archived. Check OrderState in the returned order to see if it is a canceled order.
  • Cancelled - Cancelled orders only.

PaymentStatusFilter

PaymentStatusCode

Only return orders that match the given payment status

CheckoutStatusFilter

CheckoutStatusCode

Only return orders that match the given checkout status

ShippingStatusFilter

ShippingStatusCode

Only return orders that match the given shipping status

RefundStatusFilter

OrderRefundStatusCode

Only return orders that match the given refund status

DistributionCenterCode

string

Only return orders containing at least one item from the specified distribution center.

FulfillmentTypeFilter

string

Note: This filter is not compatible with the Multiple Distribution Centers feature.
Acceptable values:
  • All - The default.  Return both seller-fulfilled and externally-fulfilled orders and line items.
  • ExternalOnly - Return only externally-fulfilled orders and line items.  Mixed orders will be returned but have seller-fulfilled line items filtered out.  Line items that are split across multiple distribution centers will also be filtered out.
  • SellerOnly - Return only seller-fulfilled orders and line items.  Mixed orders will be returned but have externally-fulfilled line items filtered out.  Line items that are split across multiple distribution centers will be returned.
  • SellerShipOnly - Returns only seller-fulfilled orders and line items with the Ship fulfillment type.  Mixed orders will be returned but have non-matching line items filtered out.
  • SellerPickupOnly - Returns only seller-fulfilled orders and line items with the Pickup fulfillment type.  Mixed orders will be returned but have non-matching line items filtered out.
  • SellerShipToStoreOnly - Returns only seller-fulfilled orders and line items with the ShipToStore fulfillment type.  Mixed orders will be returned but have non-matching line items filtered out.
  • SellerCourierOnly - Returns only seller-fulfilled orders and line items with the Courier fulfillment type.  Mixed orders will be returned but have non-matching line items filtered out.

PageNumberFilter

int

Select the page of results to return. To begin, use the value 1.

To request additional pages of data, increase this value by 1 each time you call this method to request an additional set of data.

Note: If using a value > 1, please note pages are cached at 30 minutes.

PageSize

int

The number of results to return per page. The maximum allowed page size is determined by the requested detail level.
If PageSize is omitted from the call, 20 orders (if available) will be returned in the response.

  • DetailLevel = Low allows retrieving up to 200 orders at a time.
  • DetailLevel = Medium allows retrieving up to 100 orders at a time.
  • DetailLevel = High allows retrieving up to 50 orders at a time.
  • DetailLevel = Complete allows retrieving up to 20 orders at a time.

Tips

  • To retrieve all orders that are paid and unshipped, use the following values for criteria fields: ShippingStatusFilter = Unshipped and PaymentStatusFilter = Cleared.
  • To mark an order as exported after downloading it, call this method: SetOrdersExportStatus
  • Export State is tracked by developer key, meaning that if an order is marked as exported by one developer key, it will not be considered exported by another developer key that has access to the same account.
  • See Application Example - GetOrderList by ExportState for more guidance on using GetOrderList
  • Technically all OrderCriteria fields are optional, but do not send all fields as optional or omit the OrderCriteria object entirely:
    • Make a call that includes the OrderCriteria object and all of its fields omitted (not blank) - the results returned will be as follows:
      • Since there are no filters in place, every order available for the account is in the result set
      • DetailLevel defaults to Low
      • PageNumberFilter defaults to 1
      • PageSize defaults to 20
    • As a workaround, there are filter values you can supply that will result in the same behavior as if you had omitted/nulled the field:

      • ExportState: Unknown

      • The date filters: 1900-01-01T00:00:00

      • DetailLevel: Low

      • OrderStateFilter: Active

      • The other status filters: NoChange

      • PageNumberFilter: 1

      • PageSize: 20

Notes

  • Regarding Order Criteria Omission/not-null requirement:
    • We have heard about difficulties regarding omitted filter fields from other PHP developers in the past - we believe the problem stems from a combination of the minOccurs value in the WSDL and PHP's relatively poor support for SOAP. Our understanding is that SOAP support built into the language isn't too bad most of the time, but Nusoap should be avoided if possible. 
    • The not-null requirement for the orderCriteria parameter is not reflected in the WSDL because the check against null is built into the API logic, not specified in the data contract.
  • The GetOrderList class has a lowercase "o", but uppercase "O" for the class.

  • The currency is determined by the locale of the account.

References