Skip to main content

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.)

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 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.

Addressing a package

The fulfillmentStartInstructions container includes fields with addressing information for the shipment. The following example fragment omits other fields that would normally be returned:

"fulfillmentStartInstructions": [
    {
        "ebaySupportedFulfillment": "true",
        "finalDestinationAddress": {
            "addressLine1": "123 Country Road",
            "city": "Sometown",
            "countryCode": "GB",
            "postalCode": "ST2 7CR"
        },
        "fulfillmentInstructionsType": "SHIP_TO",
        "shippingStep": {
            "shipTo": {
                "fullName": "Casey P. Buyer",
                "contactAddress": {
                    "addressLine1": "1850 Airport Exchange Blvd #200",
                    "city": "Erlanger",
                    "stateOrProvince": "KY",
                    "postalCode": "41025",
                    "countryCode": "US"
                }
            },
            "shipToReferenceId": "1234567890123456"
        }
    }
],

For domestic shipments, the shipTo container provides the buyer's name and shipping address for the address label. The finalDestinationAddress container isn't returned in that case.

However, in this example, the ebaySupportedFulfillment field is returned with a value of true, indicating that this is a Global Shipping Program shipment. The shipTo container now provides the domestic address of the international shipping provider's warehouse. The buyer's address has been moved to the finalDestinationAddress container (the seller doesn't ship to this address).

The shipToReferenceId field identifies this shipment for use with the Global Shipping Program. The international shipping provider uses the shipToReferenceId field's value as a key to retrieve the relevant details about the buyer, the order, and the fulfillment, so the shipment can be completed. Sellers must include this value on the shipping label immediately above the street address of the international shipping provider, as shown in the following address label example:

Casey P. Buyer
Reference #1234567890123456
1850 Airport Exchange Blvd #200
Erlanger KY 41025

Note: shipToReferenceId contains the same value as the ReferenceId field returned by the Trading API's GetOrders call.

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 createShippingFulfillment 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 createShippingFulfillment 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 getOrders or getOrder 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.