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.

HTTP headers for eBay REST requests

HTTP Header

Required

Description

Accept Optional

Accept indicates the formats the client accepts for the response.

This header pairs with the Content-Type header, which specifies the format required by eBay for the request. Currently, all eBay REST interfaces require request bodies to be formatted in JSON, and JSON is the default and only format returned in response bodies.

Example:
  Accept: application/json

Accept-Charset

Optional

Accept-Charset indicates the character sets the client accepts for the response.

If the server cannot respond using the value specified in Accept-Charset, the server usually ignores the value and without an error responds in utf-8.

Example:
  Accept-Charset: utf-8

Accept-Encoding

Optional –
Conditionally recommended

Accept-Encoding indicates the compression-encoding algorithms the client accepts for the response.

We strongly recommend you include this header in all requests that can potentially return large response payloads. Compression encoding can increase performance by dramatically reducing response-payload size.

Currently, application/gzip is the only supported compression format.

Example:
  Accept-Encoding: application/gzip

Accept-Language

Optional

Accept-Language indicates the natural language the client prefers for the response. This specifies the language the client wants to use when the field values provided in the request body are displayed to consumers.

Specify either a language code or a language code with a locale option. For example, use en-US for United States English and en-GB for British English. For a list of the values supported by the eBay marketplaces, see below: Marketplace ID values

The server's response includes a Content-Language header, which describes the natural language used in the response. If the server cannot respond using the value specified in Accept-Language, the server usually ignores the value and without an error responds with en-US.

Example:
  Accept-Language: de-DE

Authorization

Required

Authorization specifies the OAuth token and token type used to authorize the request.

You must supply this request header in each request you make to the eBay REST interfaces. For details, see OAuth access tokens.

Example:
  Authorization: Bearer <accessToken>

Content-Language

Conditionally required

Content-Language indicates the locale preferred by the client for the response.

While recommended for all requests, you must supply this header when you are targeting the specific locale of a marketplace that supports multiple locales. For example:

  • Use nl-BE targeting the Nederlandse locale of the Belgium marketplace
  • Use fr-CA when targeting the Française locale of the Canadian marketplace

For the language values and locales supported by the different eBay marketplaces, see the table below, Marketplace ID values.

Content-Type

Conditionally required

Content-Type indicates the format of the request body provided by the client.

This header is required for all POST and PUT operations; application/json is currently the only supported value.

Example:
  Content-Type: application/json

X-EBAY-C-MARKETPLACE-ID

Conditionally required

X-EBAY-C-MARKETPLACE-ID identifies the user's business context and is specified using a marketplace ID value.

Some API methods require this request header, the details of which are indicated on the API Reference pages of the individual API methods. Note that this header does not indicate a language preference or consumer location.

For supported values, see the table below, Marketplace ID values.

Examples:
  X-EBAY-C-MARKETPLACE-ID: EBAY_US
  X-EBAY-C-MARKETPLACE-ID: EBAY_MOTORS

X-EBAY-C-ENDUSERCTX

Optional –
Conditionally recommended

X-EBAY_C_ENDUSERCTX provides various types of information associated with the request.

We strongly recommend you use this header for certain types of requests to indicate information such as a location, affiliate details, and so on, The API Reference pages for the individual API methods reveal details about when this header is needed and how you should use it.

Example:
  X-EBAY-C-ENDUSERCTX:
   affiliateCampaignId=<ePNCampaignId>,affiliateReferenceId=<referenceId>,
   contextualLocation=country=<2-digitCountryCode>,zip=<zipCode>,
   deviceId=<riskCorrelationId>

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 the set of supported Marketplace IDs, their associated countries, the URLs to the marketplaces, and the locales supported by each marketplace:

Marketplace IDs Country Marketplace Site

Locale Support

EBAY_US United States https://www.ebay.com en-US, pt-BR, ru-RU
EBAY_AT Austria https://www.ebay.at de-AT
EBAY_AU Australia https://www.ebay.com.au en-AU
EBAY_BE Belgium https://www.befr.ebay.be/ (Française)
https://www.benl.ebay.be/ (Nederlandse)
fr-BE, nl-BE
EBAY_CA Canada https://www.ebay.ca (English)
https://www.cafr.ebay.ca/ (Française)
en-CA, fr-CA
EBAY_CH Switzerland https://www.ebay.ch de-CH
EBAY_DE Germany https://www.ebay.de de-DE
EBAY_ES Spain https://www.ebay.es es-ES
EBAY_FR France https://www.ebay.fr fr-FR
EBAY_GB Great Britain https://www.ebay.co.uk en-GB
EBAY_HK Hong Kong https://www.ebay.com.hk zh-HK
EBAY_IE Ireland https://www.ebay.ie en-IE
EBAY_IN India https://www.ebay.in en-GB
EBAY_IT Italy https://www.ebay.it it-IT
EBAY_MY Malaysia https://www.ebay.com.my en-US
EBAY_NL Netherlands https://www.ebay.nl nl-NL
EBAY_PH Philippines https://www.ebay.ph en-PH
EBAY_PL Poland https://www.ebay.pl pl-PL
EBAY_SG Singapore https://www.ebay.com.sg en-US
EBAY_TH Thailand https://info.ebay.co.th th-TH
EBAY_TW Taiwan https://www.ebay.com.tw zh-TW
EBAY_VN Vietnam https://www.ebay.vn en-US
EBAY_MOTORS_US United States https://www.ebay.com/motors
(Resolves to the parent "Auto Parts and Vehicles" category on the EBAY_US site.)
en-US

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:

HTTP methods

HTTP Method

Description

POST

POST methods request that the server accept the entity enclosed in the request as a new subordinate of the web resource identified by the URI. As examples, the POSTed data could be an annotation for existing resources; a message for a bulletin board, newsgroup, mailing list, or comment thread; a block of data that is the result of submitting a web form to a data-handling process; or an item to add to a database.

PUT

PUT methods request that the enclosed entity (passed in the body of the request) be stored under the supplied URI. If the URI refers to an already existing resource, the resource is modified. If the URI does not point to an existing resource, then the server can create the resource with that URI.

GET

GET methods request a representation of the specified resource. For example, a method that retrieves an address resource gets a representation of a specific address resource (or set of address resources). Requests using GET should only retrieve data, they should have should have no other effect or side-effect.

DELETE

DELETE methods remove the specified resource(s).

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 (or resource group) upon which the operation acts. As an example, the following is a URI that is used in a Post-Order API operation that uses a GET HTTP method:

https://api.ebay.com/post-order/v2/return/{returnId}?fieldgroups={groupEnum}

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

The components of an eBay REST URI

URI Property

Description

https://api.ebay.com

The API location.
eBay supports different API environments, such as the production environment and the Sandbox environment. See eBay API environments for details on how to address the supported eBay API environments.

/post-order

The API name.

/v2

The major version of the API.

/return

The resource upon which the operation acts. Unless the URI addresses a specific resource, the operation address a resource collection (a resource collection is a set of like resources).

/{returnId}

Known as a path parameter, these are most often used to specify a specific resource within a resource group. Here, this path parameter points to a specific ID that points to a unique resource within a collection.

?fieldgroups={groupEnum}

A few operations also support one or more query parameters, which provide for more control over what is addressed by the operation. Pay close attention to the operations that support query parameters because these parameters provide great control over what is addressed or returned by the operation.

Tip: Although you might hear the URI of an operation called an endpoint, that term is not officially part of the REST vocabulary as described by the framers of the REST architecture. However, to those who are versed in SOA APis, the term "endpoint" is familiar and it can provide for an easy way to talk about REST operations.

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:

URL Encoding Query Parameter Values

Path Parameter Value

URL Encoded Value

shirt shirt
15724 15724
categoryId:15724,Color:{Red} categoryId%3A15724%2CColor%3A%7BRed%7D

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:

REST API environments
API Location Description

https://api.ebay.com

Production environment: This API location points to the production environment where you calls affect live listings, users, inventory, and so on.

https://api.sandbox.ebay.com

Sandbox environment: This API location points to the Sandbox environment, the testing environment.

Use this environment when you are in the development phase of your application life cycle—calls made to the Sandbox do not affect live listings, users, inventory, and so on.

For details on how to test using the Sandbox, see Testing your eBay applications in the Sandbox.

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, request and response payloads are always 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"
}