Every eBay REST API method requires at least one HTTP request header, and some methods require several headers. 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.
Note: All headers should be treated as case-insensitive and must follow RFC standards.
HTTP headers for eBay REST requests
|
HTTP Header
|
Required
|
Description
|
|
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>
|
|
Accept
|
Conditionally required
|
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 body. Currently, most eBay REST interfaces require request bodies to be formatted in JSON. See Content-Type Header for details and other supported headers.
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, gzip is the only supported compression format.
Example:
Accept-Encoding: gzip
|
|
Accept-Language
|
Conditionally required
|
Accept-Language indicates the natural language and 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
fr-BE when targeting the Française 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 Marketplace ID values.
Example:
Accept-Language: fr-CA
|
|
Content-Type
|
Conditionally required
|
Content-Type indicates the format of the request body provided by the client.
This header pairs with the Accept header, which indicates the formats the client accepts for the response. Currently, all Accept headers are formatted in JSON. See Accept Header for details.
This header is usually required for all POST and PUT operations. If omitted in the request, this header defaults to application/json. Supported values include:
Content-Type: application/json
Content-Type: multipart/form-data
Content-Type: application/octet-stream
|
|
Content-Language
|
Conditionally required
|
This header sets the natural language that will be used in request payload fields that support user-defined text. Supported values for this header include en-US for English or de-DE for German.
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
fr-BE when targeting the Française 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 Marketplace ID values.
|
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:
REST API endpoints
You make a RESTful request by addressing a REST operation, which is made up of an HTTP method and an associated Uniform Resource Identifier (URI).
HTTP methods
All available HTTP methods are defined by the W3C in RFC 9110, Section 9.3. The following table shows the HTTP methods that eBay REST APIs support:
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 no other effect or side-effect. |
DELETE |
DELETE methods remove the specified resource(s). |
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:
The components of an eBay REST URI
|
URI Property
|
Description
|
https://api.ebay.com |
The domain where the API resides (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. |
/sell |
The API context (such as Buy, Sell, Commerce, or Developer). |
/fulfillment |
The API name. |
/v1 |
The major version of the API. |
/order |
The resource upon which the operation acts. Some methods may act upon a specific instance of a resource, and other methods may act upon/retrieve multiple instances of the resource. Unless the URI addresses a specific resource, the operation addresses a resource collection (a resource collection is a set of like resources). |
/{orderId} |
Known as a path parameter, these are most often used to specify a specific instance of a resource. |
?fieldGroups=string |
Some operations support one or more query parameters, which provide for more control over what is addressed by the operation. |
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.
- Separate multiple query parameters with an ampersand ("&"). Query parameters can be optional, conditionally required, or mandatory depending on the design of the REST method..
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 sandbox environment
Most eBay REST APIs support a sandbox environment where applications can be tested with various APIs before moving to the production environment. The reference documentation for each method within a REST API will contain the Production URI and the Sandbox URI. Generally, the base URI paths are very similar. So if the base Production URI is https://api.ebay.com, the Sandbox URI will be https://api.sandbox.ebay.com.
For details on how to test using the sandbox, see Create a test sandbox user.
Request payload
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 sample request payload is for a POST https://api.ebay.com/sell/marketing/v1/item_promotion request, a method 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": "2025-02-11T19:58:18.918Z",
"promotionStatus": "DRAFT"
}