Fulfillment API (v1.19.18)

Download OpenAPI specification:Download

Use the Fulfillment API to complete the process of packaging, addressing, handling, and shipping each order on behalf of the seller, in accordance with the payment method and timing specified at checkout.

order

getOrder

Use this call to retrieve the contents of an order based on its unique identifier, orderId. This value was returned in the getOrders call's orders.orderId field when you searched for orders by creation date, modification date, or fulfillment status. Include the optional fieldGroups query parameter set to TAX_BREAKDOWN to return a breakdown of the taxes and fees.

The returned Order object contains information you can use to create and process fulfillments, including:

  • Information about the buyer and seller
  • Information about the order's line items
  • The plans for packaging, addressing and shipping the order
  • The status of payment, packaging, addressing, and shipping the order
  • A summary of monetary amounts specific to the order such as pricing, payments, and shipping costs
  • A summary of applied taxes and fees, and optionally a breakdown of each

Authorizations:
Authorization_Code
path Parameters
orderId
required
string

The unique identifier of the order. Order ID values are shown in My eBay/Seller Hub, and are also returned by the getOrders method in the orders.orderId field.

query Parameters
fieldGroups
string

The response type associated with the order. The only presently supported value is TAX_BREAKDOWN. This type returns a breakdown of tax and fee values associated with the order.

Responses

Response samples

Content type
application/json
{
  • "buyer": {
    },
  • "buyerCheckoutNotes": "string",
  • "cancelStatus": {
    },
  • "creationDate": "string",
  • "ebayCollectAndRemitTax": true,
  • "fulfillmentHrefs": [
    ],
  • "fulfillmentStartInstructions": [
    ],
  • "lastModifiedDate": "string",
  • "legacyOrderId": "string",
  • "lineItems": [
    ],
  • "orderFulfillmentStatus": "string",
  • "orderId": "string",
  • "orderPaymentStatus": "string",
  • "paymentSummary": {
    },
  • "pricingSummary": {
    },
  • "program": {
    },
  • "salesRecordReference": "string",
  • "sellerId": "string",
  • "totalFeeBasisAmount": {
    },
  • "totalMarketplaceFee": {
    }
}

getOrders

Use this call to search for and retrieve one or more orders based on their creation date, last modification date, or fulfillment status using the filter parameter. You can alternatively specify a list of orders using the orderIds parameter. Include the optional fieldGroups query parameter set to TAX_BREAKDOWN to return a breakdown of the taxes and fees.

The returned Order objects contain information you can use to create and process fulfillments, including:

  • Information about the buyer and seller
  • Information about the order's line items
  • The plans for packaging, addressing and shipping the order
  • The status of payment, packaging, addressing, and shipping the order
  • A summary of monetary amounts specific to the order such as pricing, payments, and shipping costs
  • A summary of applied taxes and fees, and optionally a breakdown of each


Important: In this call, the cancelStatus.cancelRequests array is returned but is always empty. Use the getOrder call instead, which returns this array fully populated with information about any cancellation requests.

Authorizations:
Authorization_Code
query Parameters
fieldGroups
string

The response type associated with the order. The only presently supported value is TAX_BREAKDOWN. This type returns a breakdown of tax and fee values associated with the order.

filter
string

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. Multiple filter criteria combine to further restrict the results.

Note: Currently, filter returns data from only the last 90 days. If the orderIds parameter is included in the request, the filter parameter will be ignored.

The available criteria are as follows:

creationdate
The time period during which qualifying orders were created (the orders.creationDate field). In the URI, this is expressed as a starting timestamp, with or without an ending timestamp (in brackets). The timestamps are in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.For example:
  • creationdate:[2016-02-21T08:25:43.511Z..] identifies orders created on or after the given timestamp.
  • creationdate:[2016-02-21T08:25:43.511Z..2016-04-21T08:25:43.511Z] identifies orders created between the given timestamps, inclusive.
lastmodifieddate
The time period during which qualifying orders were last modified (the orders.modifiedDate field). In the URI, this is expressed as a starting timestamp, with or without an ending timestamp (in brackets). The timestamps are in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.For example:
  • lastmodifieddate:[2016-05-15T08:25:43.511Z..] identifies orders modified on or after the given timestamp.
  • lastmodifieddate:[2016-05-15T08:25:43.511Z..2016-05-31T08:25:43.511Z] identifies orders modified between the given timestamps, inclusive.
Note: If creationdate and lastmodifieddate are both included, only creationdate is used.

orderfulfillmentstatus
The degree to which qualifying orders have been shipped (the orders.orderFulfillmentStatus field). In the URI, this is expressed as one of the following value combinations:
  • orderfulfillmentstatus:{NOT_STARTED|IN_PROGRESS} specifies orders for which no shipping fulfillments have been started, plus orders for which at least one shipping fulfillment has been started but not completed.
  • orderfulfillmentstatus:{FULFILLED|IN_PROGRESS} specifies orders for which all shipping fulfillments have been completed, plus orders for which at least one shipping fulfillment has been started but not completed.
Note: The values NOT_STARTED, IN_PROGRESS, and FULFILLED can be used in various combinations, but only the combinations shown here are currently supported.
Here is an example of a getOrders call using all of these filters:

GET https://api.ebay.com/sell/v1/order?
filter=creationdate:%5B2016-03-21T08:25:43.511Z..2016-04-21T08:25:43.511Z%5D,
lastmodifieddate:%5B2016-05-15T08:25:43.511Z..%5D,
orderfulfillmentstatus:%7BNOT_STARTED%7CIN_PROGRESS%7D


Note: This call requires that certain special characters in the URI query string be percent-encoded:
    [ = %5B       ] = %5D       { = %7B       | = %7C       } = %7D
This query filter example uses these codes.
For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/fulfillment/types/api:FilterField

limit
string

The number of orders to return per page of the result set. Use this parameter in conjunction with the offset parameter to control the pagination of the output.

For example, if offset is set to 10 and limit is set to 10, the call retrieves orders 11 thru 20 from the result set.

If a limit is not set, the limit defaults to 50 and returns up to 50 orders. If a requested limit is more than 200, the call fails and returns an error.

Note: This feature employs a zero-based list, where the first item in the list has an offset of 0. If the orderIds parameter is included in the request, this parameter will be ignored.

Maximum: 200
Default: 50

offset
string

Specifies the number of orders to skip in the result set before returning the first order in the paginated response.

Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.

Default: 0

orderIds
string

A comma-separated list of the unique identifiers of the orders to retrieve (maximum 50). If one or more order ID values are specified through the orderIds query parameter, all other query parameters will be ignored.

Responses

Response samples

Content type
application/json
{
  • "href": "string",
  • "limit": 0,
  • "next": "string",
  • "offset": 0,
  • "orders": [
    ],
  • "prev": "string",
  • "total": 0,
  • "warnings": [
    ]
}

Issue Refund

Important! Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made on behalf of EU/UK sellers, including issueRefund. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signatures to be included in the HTTP payload.


This method allows a seller to issue a full or partial refund to a buyer for an order. Full or partial refunds can be issued at the order level or line item level.

The refunds issued through this method are processed asynchronously, so the refund will not show as 'Refunded' right away. A seller will have to make a subsequent getOrder call to check the status of the refund. The status of an order refund can be found in the paymentSummary.refunds.refundStatus field of the getOrder response.
Authorizations:
Authorization_Code
path Parameters
order_id
required
string

The unique identifier of the order. Order IDs are returned in the getOrders method (and GetOrders call of Trading API). The issueRefund method supports the legacy API Order IDs and REST API order IDs.

header Parameters
X-EBAY-C-MARKETPLACE-ID
string

This header identifies the seller's eBay marketplace. It is required for all marketplaces outside of the US. See HTTP request headers for the marketplace ID values.

Request Body schema: application/json
reasonForRefund
string

The enumeration value passed into this field indicates the reason for the refund. One of the defined enumeration values in the ReasonForRefundEnum type must be used.

This field is required, and it is highly recommended that sellers use the correct refund reason, especially in the case of a buyer-requested cancellation or 'buyer remorse' return to indicate that there was nothing wrong with the item(s) or with the shipment of the order.

Note: If issuing refunds for more than one order line item, keep in mind that the refund reason must be the same for each of the order line items. If the refund reason is different for one or more order line items in an order, the seller would need to make separate issueRefund calls, one for each refund reason. For implementation help, refer to eBay API documentation

comment
string

This free-text field allows the seller to clarify why the refund is being issued to the buyer.

Max Length: 100

Array of objects (RefundItem)

The refundItems array is only required if the seller is issuing a refund for one or more individual order line items in a multiple line item order. Otherwise, the seller just uses the orderLevelRefundAmount container to specify the amount of the refund for the entire order.

object (SimpleAmount)

This type defines the monetary value of the refund amount, and the currency used.

Responses

Request samples

Content type
application/json
{
  • "reasonForRefund": "string",
  • "comment": "string",
  • "refundItems": [
    ],
  • "orderLevelRefundAmount": {
    }
}

shipping_fulfillment

getShippingFulfillments

Use this call to retrieve the contents of all fulfillments currently defined for a specified order based on the order's unique identifier, orderId. This value is returned in the getOrders call's members.orderId field when you search for orders by creation date or shipment status.

Authorizations:
Authorization_Code
path Parameters
orderId
required
string

The unique identifier of the order. Order ID values are shown in My eBay/Seller Hub, and are also returned by the getOrders method in the orders.orderId field.

Responses

Response samples

Content type
application/json
{
  • "fulfillments": [
    ],
  • "total": 0,
  • "warnings": [
    ]
}

createShippingFulfillment

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.

Authorizations:
Authorization_Code
path Parameters
orderId
required
string

The unique identifier of the order. Order ID values are shown in My eBay/Seller Hub, and are also returned by the getOrders method in the orders.orderId field.

Request Body schema: application/json

fulfillment payload

Array of objects (LineItemReference)

This array contains a list of or more line items and the quantity that will be shipped in the same package.

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.

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.

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

Responses

Request samples

Content type
application/json
{
  • "lineItems": [
    ],
  • "shippedDate": "string",
  • "shippingCarrierCode": "string",
  • "trackingNumber": "string"
}

Response samples

Content type
application/json
{ }

getShippingFulfillment

Use this call to retrieve the contents of a fulfillment based on its unique identifier, fulfillmentId (combined with the associated order's orderId). The fulfillmentId value was originally generated by the createShippingFulfillment call, and is returned by the getShippingFulfillments call in the members.fulfillmentId field.

Authorizations:
Authorization_Code
path Parameters
fulfillmentId
required
string

The unique identifier of the fulfillment. This eBay-generated value was created by the Create Shipping Fulfillment call, and returned by the getShippingFulfillments call in the fulfillments.fulfillmentId field; for example, 9405509699937003457459.

orderId
required
string

The unique identifier of the order. Order ID values are shown in My eBay/Seller Hub, and are also returned by the getOrders method in the orders.orderId field.

Responses

Response samples

Content type
application/json
{
  • "fulfillmentId": "string",
  • "lineItems": [
    ],
  • "shipmentTrackingNumber": "string",
  • "shippedDate": "string",
  • "shippingCarrierCode": "string"
}