createShippingFulfillment: eBay Fulfillment API

POST/order/{orderId}/shipping_fulfillment

When you group an order's line items into one or more packages, each package requires a corresponding plan for handling, addressing, and shipping; this is a shipping fulfillment. For each package, execute this call once to generate a shipping fulfillment associated with that package.

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 must include all components of a given line item in the same package.

Before using this call for a given package, you must determine which line items are in the package. If the package has been shipped, you should provide the date of shipment in the request. If not provided, it will default to the current date and time.

Input

Resource URI

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

This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com

URI parameters

Parameter	Type	Description
orderId	string	This path parameter is used to specify the unique identifier of the order associated with the shipping fulfillment being created. Use the getOrders method to retrieve order IDs. Occurrence: Required

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.

Header	Type	Description
Content-Type	string	This header indicates the format of the request body provided by the client. Its value should be set to application/json. For more information, refer to HTTP request headers. Occurrence: Required

Header

Type

Description

Content-Type

string

This header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers.

Occurrence: Required

OAuth scope

This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/sell.fulfillment

See OAuth access tokens for more information.

Request payload

Copy complete valid JSON to clipboard

{ /* ShippingFulfillmentDetails */

"lineItems" : [

{ /* LineItemReference */

"lineItemId" : "string",

"quantity" : "integer"

}

"shippedDate" : "string",

"shippingCarrierCode" : "string",

"trackingNumber" : "string"

}

Request fields

Input container/field	Type	Description
lineItems	array of LineItemReference	This array contains a list of or more line items and the quantity that will be shipped in the same package. Occurrence: Required
lineItems.lineItemId	string	This is the unique identifier of the eBay order line item that is part of the shipping fulfillment. Line item Ids can be found in the lineItems.lineItemId field of the getOrders response. Occurrence: Required
lineItems.quantity	integer	This is the number of lineItems associated with the trackingNumber specified by the seller. This must be a whole number greater than zero (0). Default: 1 Occurrence: Optional
shippedDate	string	This is the actual date and time that the fulfillment package was shipped. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. The seller should use the actual date/time that the package was shipped, but if this field is omitted, it will default to the current date/time. Format: `[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z` Example: `2015-08-04T19:09:02.768Z` Default: The current date and time. Occurrence: Optional
shippingCarrierCode	string	The unique identifier of the shipping carrier being used to ship the line item(s). Technically, the shippingCarrierCode and trackingNumber fields are optional, but generally these fields will be provided if the shipping carrier and tracking number are known. Note: Use the Trading API's GeteBayDetails call to retrieve the latest shipping carrier enumeration values. When making the GeteBayDetails call, include the DetailName field in the request payload and set its value to `ShippingCarrierDetails`. Each valid shipping carrier enumeration value is returned in a ShippingCarrierDetails.ShippingCarrier field in the response payload. Occurrence: Conditional
trackingNumber	string	The tracking number provided by the shipping carrier for this fulfillment. The seller should be careful that this tracking number is accurate since the buyer will use this tracking number to track shipment, and eBay has no way to verify the accuracy of this number. This field and the shippingCarrierCode field are mutually dependent. If you include one, you must also include the other. Note: If you include trackingNumber (and shippingCarrierCode) in the request, the resulting fulfillment's ID (returned in the HTTP location response header) is the tracking number. If you do not include shipment tracking information, the resulting fulfillment ID will default to an arbitrary number such as `999`. Note: Only alphanumeric characters are supported for shipment tracking numbers. Spaces, hyphens, and all other special characters are not supported. Do not include a space in the tracking number even if a space appears in the tracking number on the shipping label. Occurrence: Conditional

Output

HTTP response headers

See HTTP response headers for details.

Header	Meaning
Location	The location response header contains the getShippingFulfillment URI to retrieve the contents of the newly created shipping fulfillment. The URL includes the eBay-assigned `fulfillmentId`, which you can use to reference the shipping fulfillment.

Response payload

This call has no payload.

Response fields

This call has no field definitions.

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

Status	Meaning
201	Created. The call also returns the following location response header: `{ENV}/sell/fulfillment/v1/order/{ORDERID}/shipping_fulfillment/{FULFILLMENTID}` The `ENV` string is the HTTPS path to the same eBay supported environment in which this call was issued. The `ORDERID` parameter is the unique identifier of the order addressed by this call; for example, `01-03955-36441`. The `FULFILLMENTID` parameter identifies the newly created fulfillment; for example, `9405509699937003457459`. Use this Get Fulfillment URI to retrieve the contents of the new fulfillment.
400	Bad Request
409	Conflict
500	Internal Server Error. Note: In some cases, this call may succeed if you issue it once more after receiving this error.

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

Code	Domain	Category	Meaning
30500	API_FULFILLMENT	APPLICATION	System error
32100	API_FULFILLMENT	REQUEST	Invalid Order Id: {orderId}
32200	API_FULFILLMENT	REQUEST	Invalid line item id: {lineItemId}
32210	API_FULFILLMENT	REQUEST	Duplicate line item in the request
32300	API_FULFILLMENT	REQUEST	Invalid shipment tracking number or carrier
32400	API_FULFILLMENT	REQUEST	Requested user is suspended
32500	API_FULFILLMENT	REQUEST	Invalid shipped date
32600	API_FULFILLMENT	REQUEST	Invalid input data
34100	API_FULFILLMENT	REQUEST	Maximum tracking number for order is exceeded
34200	API_FULFILLMENT	REQUEST	Line Items contain Global Shipping Program and non-Global Shipping Program orders
34300	API_FULFILLMENT	REQUEST	Mark As Shipped for multiple Global Shipping Program line items is not supported
34500	API_FULFILLMENT	REQUEST	Please use PUT operation for updating shipping fulfillment

Warnings

This call has no warnings.

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Create a Shipping Fulfillment

This sample creates a new shipping fulfillment with an eBay-generated fulfillment ID, containing the specified line items.

Input

Use the orderid parameter to specify the order for which you are creating a shipping fulfillment. Identify the lineItems included in the package, as well as the shipping information if the package has been shipped.

POSThttps://api.ebay.com/sell/fulfillment/v1/order/6********5!2********1/shipping_fulfillment

Output

A successful call returns an HTTP status code of 201 (Created). It also returns a location header response for the newly created shipping fulfillment resource, including its fulfillment ID:

https://api.ebay.com/sell/fulfillment/v1/order/6********5!2********1/shipping_fulfillment/1********6

Note: Currently, eBay uses the value of the submitted tracking number as the new fulfillment ID, but don't depend on this behavior. The fulfillment ID format is subject to change in the future.This call has no response payload.