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 > Handling unfulfilled line items

Handling unfulfilled line items

To discover unfulfilled orders, see Discovering unfulfilled orders. Once you've discovered an unfulfilled order, you need to determine whether any of the order's line items remain that have not been assigned to a shipping fulfillment, or have been assigned to a shipping fulfillment but not fulfilled. (When you fulfill all of the order's line items, the order itself is considered to be fulfilled. )

Topics:

Determining line item fulfillment status

Using the fulfillment start instructions

Creating shipping fulfillments

Determining line item fulfillment status

If the order's orderFulfillmentStatus field has a value of NOT_STARTED, none of its line items are assigned to a shipping fulfillment. Continue to Using the fulfillment start instructions.

If the order's orderFulfillmentStatus field has a value of IN_PROGRESS, you must check the fulfillment status of every line item. For each line item in the order, examine the lineItemFulfillmentStatus field.

  • Line items for which this field has a value of NOT_STARTED have not been assigned to a shipping fulfillment. Continue to Using the fulfillment start instructions.
  • Line items for which this field has a value of IN_PROGRESS or FULFILLED have been packaged and assigned to a shipping fulfillment. You can proceed to complete the fulfillment process for the order; see Managing fulfillments for an order.

Using the fulfillment start instructions

The order's FulfillmentStartInstructions object contains a list of one or more sets of specifications for fulfilling the order. Each set can include the type of fulfillment, shipping service, addressing details, and estimated delivery window. These instructions are derived from the buyer's and seller's eBay account preferences, the listing parameters, and the buyer's checkout selections. The fulfillment start instructions are not mandatory; they just provide you and the seller with a recommended starting point for packaging, addressing, and shipping the order.

Important! Currently, the Fulfillment API does not allow you to add or subtract line items from existing shipping fulfillments (or packages). You must be certain of the seller's packaging choices, because you will not be able to change the allocation of line items. The capability to make changes in a fulfillment will be added in a future release.

Creating shipping fulfillments

For all line items with a lineItemFulfillmentStatus field value of NOT_STARTED, the seller must allocate them among new packages, for which you create new shipping fulfillments. You help the seller ensure that every line item in the order is assigned to a package.

The seller must decide which line items in an order will be in each package to be shipped. Each package requires a corresponding shipping fulfillment.

Note: A single line item in an order can consist of multiple units of a purchased item, and one unit can consist of multiple parts or components. Although these components might be provided by the manufacturer in separate packaging, the seller cannot distribute them among multiple shipping packages. Only one tracking number can be assigned to each line item, so all components of the line item must be in the same package.

To create a shipping fulfillment, use the Fulfillment API's Create a Shipping Fulfillment call. The URI takes this form:

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

Insert the orderId value for your order that needs to be fulfilled, for example:

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

The call request payload should include, at minimum, a list of lineItems that will be part of this package. If the package has been shipped, provide the shippedDate in the request. If not provided, it will default to the current date and time. You can also include the shippingCarrierCode and the trackingNumber (if you include one of these, you must also include the other). For example:

{
    "lineItems": [
        { 
            "lineItemId": "9876543210", 
            "quantity": 1 
        }
    ],
    "shippedDate": "2016-07-20T00:00:00.000Z",
    "shippingCarrierCode": "USPS",
    "trackingNumber": "123456789012345678"
}

A successful Create a Shipping Fulfillment call does not produce a response payload. It returns an HTTP status code of 201, along with a location code for the newly created shipping_fulfillment resource. For example:

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

Once you have created shipping fulfillments for all line items in the order, their lineItemFulfillmentStatus field will have a value of IN_PROGRESS or FULFILLED the next time you retrieve the order using the Get Orders or Get an Order call. The seller must finish packaging and shipping the order according to the shipping fulfillments to which its line items are assigned. See Managing fulfillments for an order.