This doc page has moved! You should be automatically redirected to the new location. If you are not redirected automatically, follow this link to the new page.

You are here: Sell APIs > Selling Integration Guide > Handling orders > Discovering unfulfilled orders

Discovering unfulfilled orders

You retrieve unfulfilled orders so you can create and process each order's shipping fulfillments. Unfulfilled orders include those for which no packages are defined, and those for which at least one package is defined but no packages have been shipped.

If you store the order IDs of newly checked out orders, you might prefer to retrieve those orders directly for fulfillment processing. If you don't store order IDs, you might need to use filtering to find the orders of a given seller that need fulfilling. You will also need to periodically check each order's fulfillment status until it is complete.

Topics:

Retrieving known orders

Searching for orders

Determining order fulfillment status

Retrieving known orders

If you have the order IDs of one or more known orders that have completed checkout, you can retrieve those orders to check their fulfillment status.

Getting a single known order

Use the Fulfillment API's Get an Order call to retrieve the known order. The resource URI takes this form:

GET https://api.ebay.com/sell/fulfillment/v1/order/{orderId}

Insert the orderId value for your known order, for example:

GET https://api.ebay.com/sell/fulfillment/v1/order/6498414015!260000000562911

Getting multiple known orders

Use the Fulfillment API's Get Orders call to retrieve multiple known orders.The resource URI takes this form:

GET https://api.ebay.com/sell/fulfillment/v1/order?
orderids=string

Insert a comma-separated list of orderids of the orders to retrieve (maximum 50). For example:

GET https://api.ebay.com/sell/fulfillment/v1/order?
   orderids=6498414015!260000000562911,9849164007!140000000544476

These orderId values were originally generated by eBay as a result of the buyer's checkout process. Multiple orderId values are also returned in the orders.orderId field by invoking this call with filter parameters.

Searching for orders

Use theFulfillment API's Get Orders call to retrieve the authenticated seller's orders. You can search for and retrieve one or more orders based on their creation date, last modification date, or fulfillment status using the filter parameter.

Note: Currently, filter returns data from only the last 90 days.

The resource URI takes this form:

GET https://api.ebay.com/sell/fulfillment/v1/order?
filter=FilterField&
limit=string&
offset=string

The value of filter can be one or more comma-separated criteria for narrowing down the collection of orders returned by this call. These criteria correspond to specific fields in the response payload. The fields include:

  • order.creationDate, which you provide as a starting date and an end date separated by ".."

  • order.modifiedDate, which you provide as a starting date and an end date separated by ".."

  • order.orderFulfillmentStatus, which you provide as one or more enumeration values separated by "|" (a logical OR)

Combine these criteria to further restrict the results.

Note: This call requires that certain special characters in the URI query string be percent-encoded:
    [ = %5B     ] = %5D     { = %7B     | = %7C     } = %7D

Finding orders by creation date

The following example uses the creationdate parameter to specify all orders created after the given timestamp. Note the use of percent-encoded characters. An ending date is not given:

GET https://api.ebay.com/sell/fulfillment/v1/order?
filter=creationdate:%5B2016-09-29T15:05:43.026Z..%5D&
limit=50&
offset=0

This example limits the set of orders by time period, but not by fulfillment status.

Finding orders by fulfillment status

The following example uses the orderfulfillmentstatus parameter to specify all orders for which no shipping fulfillments have been started, plus orders for which at least one shipping fulfillment has been started but not completed. Note the use of percent-encoded characters:

GET https://api.ebay.com/sell/fulfillment/v1/order?
filter=orderfulfillmentstatus:%7BNOT_STARTED%7CIN_PROGRESS%7D&
limit=50&
offset=0

Determining order fulfillment status

Before sellers can start fulfilling orders, they need to know which orders are not yet fulfilled.

If you used the Fulfillment API's Get Orders call to find orders by fulfillment status, the example above returns unfulfilled orders.

For the other cases (retrieving orders by order ID, or those that match a specified creation or last modified date range), examine the orderFulfillmentStatus field in the response. Unfulfilled orders are those in which this field has a value of NOT_STARTED or IN_PROGRESS.

Note: If the value of the orderFulfillmentStatus field is FULFILLED, the order is considered shipped. Any further attention it needs will be handled in the post-order phase.

Once you discover an unfulfilled order, your next task is to help the seller ensure that every unit and component of every line item in the order is assigned to a package, and create a shipping fulfillment for each package. See Handling unfulfilled line items.