This doc page has moved! You should be automatically redirected to the new location. If you are not redirected automatically, follow this link to the new page.

You are here: Using eBay RESTful APIs > Request components

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)
  • Call payload (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 a 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

No

This request header specifies the format of the response payload required by the caller. Currently, the eBay REST interfaces require payloads formatted in JSON, and JSON is the default.

Example:
  Accept: application/json

Accept-Charset

No

This request header specifies the character set the client accepts. The Content-Type response header defines character set of the result, which should be the same value as the Accept-Charset request header. If the server cannot return a result in the value specified by Accept-Charset, the server usually ignores the header (no error code is returned).

Example:
  Accept-Charset: utf-8

Accept-Encoding

Optional

This request header is strongly recommended for calls that return large payloads. It specifies the response compression encoding algorithm required by the caller. For large payloads, compression encoding can dramatically reduce payload size and increase call performance. Currently, application/gzip is the only allowed value.

Example:
  Accept-Encoding: application/gzip

Accept-Language

No

This request header specifies the natural language in which the client desires the response. The server's response includes a Content-Language response header that describes the natural language of the response. Supply a value for this header as either a language code or a language code with a country option (for example, en-US for United States English, as opposed to British English). See Marketplace ID and language header values section below for a list of the values supported by eBay.

If the server cannot return a result in value specified in Accept-Language header, the server usually ignores the header (no error code is returned).

Example:
  Accept-Language: de-DE

Authorization

Yes

This request header must be supplied in each call you make to the eBay REST interfaces for authorization. See the following topic for details: OAuth access tokens.

Example:
  Authorization: Bearer <accessToken>

Content-Language

No

This request header describes the natural language provided in the field values of the request payload. See the table below for the language values supported by eBay.

Content-Type

No

This request header specifies the format and encoding of the request message so the called service can correctly read the request data. Currently, application/json is the only supported value and it is the default.

Example:
  Content-Type: application/json

X-EBAY-C-MARKETPLACE-ID

Conditionally

This request header is required by some API operations.

This header identifies the user's business context. See the table at the end of this document for allowed values. Note that this header does not indicate a language preference or end-user location.

Examples:
  X-EBAY-C-MARKETPLACE-ID: EBAY-US
  X-EBAY-C-MARKETPLACE-ID: EBAY-US.MOTORS

X-EBAY-C-ENDUSERCTX

Optional

This request header is strongly recommended for some API operations.

Use this header to pass in information about the user such as their location, their affiliate information, and so on.

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 operations or APIs make use of additional headers. Check the documentation of the operation for details on any additional headers that might be required to make a request to the interface.

Marketplace ID and language header values

The marketplace ID can be appended with a vertical name (e.g., MOTORS), using a dot (".") separator. For example, EBAY-US.MOTORS.

The set of supported Marketplaces and their associated languages and countries are:

Marketplace Country Supported Languages

EBAY-AU

Australia en-AU

EBAY-AT

Austria de-AT

EBAY-BE

Belgium nl-BE, fr-BE

EBAY-CA

Canada en-CA, fr-CA

EBAY-CN

China zh-HK

EBAY-FR

France fr-FR

EBAY-DE

Germany de-DE

EBAY-HK

Hong Kong zh-HK

EBAY-IN

India en-IN

EBAY-IE

Ireland en-IE

EBAY-IT

Italy it-IT

EBAY-MY

Malaysia en-MY

EBAY-NL

Netherlands nl-NL

EBAY-PH

Philippines en-PH

EBAY-PL

Poland pl-PL

EBAY-SG

Singapore en-SG

EBAY-ES

Spain es-ES

EBAY-CH

Switzerland de-CH

EBAY-GB

United Kingdom en-GB

EBAY-US

United States en-US, pt-BR, ru-RU, es-CO

EBAY-US.MOTORS

United States en-US

The REST operation

The most visible part of a REST interface is its operation name. Whenever you make a request to a REST interface, you do so by addressing its operation name.

A REST operation is made up of its HTTP method and its associated URI.

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}

Know 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.

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.

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 using the Sandbox.

The call payload

Payloads are provided with a REST interfaces when you what to create or update a resource. In our eBay REST APIs, request and response payloads are always formatted in JSON. See the documentation for each API to see what fields are supported by the operation's payload.

The following code shows an example JSON payload for a POST https://api.sandbox.ebay.com/buy/v1/session request, a call that creates a checkout session for a customer using their specified mailing address and item list:

{
  "shippingUserAddress": {
    "firstName": "Fester",
    "lastName": "Bestertester",
    "phoneNumber": "1 (866) 540-3229",
    "email": "fester@bestertester.com",
    "address": {
      "addressLine1": "2065 Hamilton Avenue",
      "addressLine2": "",
      "city": "San Jose",
      "country": "US",
      "postalCode": 95125,
      "stateOrProvince": "CA"
    }
  },
  "lineItemInputs": [
    {
      "itemId": "v1|110169811476|0",
      "quantity": 1
    }
  ]
}