Request components

All eBay REST requests contain a standard set of call components.

Parts of a REST request

Make requests to the eBay REST interfaces by combining the following in a request:

• HTTP headers
• REST operation (or endpoint)
• Request payload (or request body, as required by the operation)

HTTP request headers

You must supply a set of HTTP headers when making a request to an eBay REST operation. These headers can include both standard HTTP headers and eBay custom headers. All eBay custom headers start with "X-EBAY-C-".

Some eBay custom headers are packed headers, meaning they can contain multiple name/value pairs. The format for a name/value pair is <name>=<value>, and you must separate multiple values in a single header by commas. The following example shows the general format:

  X-EBAY-C-PACKED-EXAMPLE: fig=7,bar="quux",value=42

The table below presents the standard request headers that eBay accepts, as well as the custom eBay headers that you can use. Although not all possible request headers are listed in this table (some headers are still in flux), the ones listed here are stable.

In addition to this set of common HTTP headers, some methods or APIs make use of additional headers. Check the documentation of the method for details on any additional headers that might be required to make a request to the interface.

Marketplace ID values

The following table lists supported Marketplace IDs, their associated countries/regions, the URLs to the marketplaces, and the locales supported by each marketplace:

The REST operation

You make a RESTful request by addressing a REST operation, which is made up of an HTTP method and an associated URI. This construct is the most identifiable part of a REST interface and is commonly called the method name (and sometimes called an endpoint).

HTTP methods

HTTP methods are defined by the W3C in RFC 2616, Section 9. While the specification defines close to 10 HTTP methods, for the most part, eBay REST APIs make use of the following few HTTP methods:

While some APIs might use alternate HTTP methods, those cases are rare and their use will be explicitly described in the associated interface documentation.

REST operation URIs

The URI part of a REST operation points to the resource upon which the operation acts. As an example, the following is a URI that is used in a Fulfillment API GET operation to retrieve the contents of an order based on its unique identifier, orderId:

https://api.ebay.com/sell/fulfillment/v1/order/{orderId}?fieldGroups=string

This URI is created by combining several separate pieces of information:

URI parameters

As shown above, REST operations can include parameters in their URIs. Specifically, they can have both path parameters and query parameters:

• Path parameters are variables that are part of the "path" segment of an operation. Because these variables are part of the operation's path, they are always required.
• Query parameters are variables that are appended to the path segment of an operation's URI. After the path segment, include a question mark ("?") and the list of path parameters you want to include with your query. Separate multiple path parameter with an ampersand ("&"). Path parameters can be both optional and required.

URL encoding query parameter values

While some path parameters do not require you to include a value for the parameter to take effect, some path parameters do required you to include a value with the parameter. Consider a sort query parameter, which normally requires you to specify a field on which to sort the result.

Whenever path parameters require added values, you must URL encode the values you add. URL encoding is sometimes referred to as "percent-encoding."

Consider the following example:

/buy/browse/v1/item_summary/search?q=shirt&category_ids=15724&aspect_filter=categoryId:15724,Color:{Red}

The above URI includes three query parameters, q, category_ids, and aspect_filter. While the first two parameters are straight-forward, the third (aspect_filter) is a bit more complex, it specifies two separate values. Still, each of the values supplied to these query parameters must be URL encoded as the following table shows:

As you can see, the URL encoding for the first two values does not alter their string values. However, the third value contains some characters that, when encoded, get rendered with a special encoding. With this example, the full URL encoded URI to the operation is as follows:

/buy/browse/v1/item_summary/search?q=shirt&category_ids=15724&aspect_filter=categoryId%3A15724%2CColor%3A%7BRed%7D

For more on URL encoding, see Percent-encoding.

eBay API environments

eBay supports several different API environments to which you can make API requests. The different environments allow you to test your calls to the eBay APIs before you move your application into production. You address the specific environment you want to target using the API location part of the REST operation's URI, as defined in the REST operation URIs section above.

The following table defines the available API environments:

For details on how to test using the sandbox, see Create a test sandbox user.

The request body

A request body, often called a "payload," is provided with a request whenever you what to create or update a resource. In the eBay REST APIs, most request payloads and all response payloads are formatted in JSON. The API Reference documentation describes the fields supported in the body of each method.

The following code shows an example JSON payload for a POST https://api.ebay.com/sell/marketing/v1/item_promotion request, a call that creates an item discount:

{
    "marketplaceId": "EBAY_US",
    "inventoryCriterion": {
        "listingIds": [
            "142250172493",
            "132073034350"
        ],
        "inventoryCriterionType": "INVENTORY_BY_VALUE"
    },
    "endDate": "2027-03-01T20:00:00.000Z",
    "discountRules": [
        {
            "discountSpecification": {
                "numberOfDiscountedItems": 1,
                "forEachQuantity": 1
            },
            "ruleOrder": 0,
            "discountBenefit": {
                "percentageOffItem": "5"
            }
        }
    ],
    "name": "Buy 1 and get 2nd one 5% off -part 2",
    "description": "Buy 1 and get 2nd one 5% off -part 2",
    "startDate": "2017-02-11T19:58:18.918Z",
    "promotionStatus": "DRAFT"
}