eBay Business Policies Management API
 

Making a Call

This document explains how to make Business Policies Management API calls. It provides an overview of the formats and parameters you can use with the Business Policies Management API.

Important! eBay recommends that you use the Account API to set up all your fulfillment, payment, and return business policies. This API Reference remains active for archival purposes only.

Introduction to Service

The Business Policies Management API is a SOA service that is intended to be consumed by sellers who are interested in creating and managing payment, return, and shipping business policies to use with their eBay listings. High-level information for the service are covered below, including service endpoints, HTTP headers and URL parameters, naming conventions, and versioning scheme.

Supported Request and Response Formats

The Business Policies Management API supports XML and SOAP request and response formats.

The call response for SOAP requests is in SOAP format only.

Call Structure

Each Business Policies Management API call consists of the following elements:

Service Endpoints

Production Endpoint:

https://svcs.ebay.com/services/selling/v1/SellerProfilesManagementService

Sandbox Endpoint:

https://svcs.sandbox.ebay.com/services/selling/v1/SellerProfilesManagementService

Note: The service endpoint contains the major version for the service (e.g., v1). When updating to subsequent major releases, you must update the version in the service endpoint, as well.

Standard URL Parameter or HTTP Header Values

When you make a Business Policies Management API call, you choose whether to specify the standard values in URL parameters or in the HTTP header. URL parameters are provided as name-value pairs in the query part of the URI.

Note: If you specify both a URL parameter and an HTTP header for the same value in the same call, the URL parameter takes precedence. The values you provide in your call are case-sensitive.

The following table contains descriptions of the standard Business Policies Management API parameters and the corresponding header values:

URL Parameter Header Value Required? Description
N/A X-EBAY-SOA-CONTENT-TYPE No If you use this header, you must specify the content format exactly as shown, or your call may fail. The allowable values are:

XML text/xml
SOAP12 application/soap+xml
SOAP11 text/xml (together with SOAPAction header being sent - value can be anything)
X-EBAY-SOA-GLOBAL-ID X-EBAY-SOA-GLOBAL-ID Yes The unique identifier for a combination of site, language, and territory. For example, EBAY-US (the default) is the global ID that corresponds to the eBay US site. The global ID you specify must correspond to an eBay site with a valid site ID. Refer to eBay Site ID to Global ID Mapping. In addition, Global ID Values contains a complete list of the eBay global IDs.
X-EBAY-SOA-MESSAGE-ENCODING X-EBAY-SOA-MESSAGE-ENCODING Conditionally Specifies the message encoding (e.g., ISO-8859-1). The default encoding is UTF-8. When submitting requests in any format other than UTF-8, you must specify the message encoding.
N/A X-EBAY-SOA-MESSAGE-PROTOCOL Conditionally If you make a SOAP request, you must use this header to specify the protocol you are using. Allowable values are "SOAP11" for SOAP Version 1.1 and "SOAP12" for SOAP Version 1.2.
X-EBAY-SOA-SERVICE-NAME X-EBAY-SOA-SERVICE-NAME No The name of the service you are using. Specify "SellerProfilesManagementService" for all Business Policies Management API calls.
X-EBAY-SOA-OPERATION-NAME X-EBAY-SOA-OPERATION-NAME Yes The name of the call you are using (for example, addSellerProfile or getSellerProfiles).
X-EBAY-SOA-REQUEST-DATA-FORMAT X-EBAY-SOA-REQUEST-DATA-FORMAT No The Business Policies Management API supports XML and SOAP request formats with the HTTP POST method. Input can be in XML or SOAP formats. The default value for HTTP POST requests is XML.
For SOAP requests, you must specify the protocol version in the X-EBAY-SOA-MESSAGE-PROTOCOL header. If you use a URL for an HTTP GET request, REQUEST-DATA-FORMAT is unnecessary because the only valid value is NV (Name-Value Pair).
X-EBAY-SOA-RESPONSE-DATA-FORMAT X-EBAY-SOA-RESPONSE-DATA-FORMAT No If you use a URL (HTTP GET) request, use this parameter to specify the output format as XML. URL requests do not support SOAP responses. If you use a URL, and you do not specify RESPONSE- DATA-FORMAT, the output format will be XML. If you use the HTTP POST method, the output data (response data) will be in the same format as the input data.
REST-PAYLOAD N/A No If you use a URL, use this parameter to separate the payload part of the URL from the standard headers. Requires no value; anything appearing after this header will be considered part of the call payload. This parameter is ignored in HTTP POST requests.
X-EBAY-SOA-SECURITY-IAFTOKEN X-EBAY-SOA-SECURITY-IAFTOKEN Conditionally Required if you do not supply an X-EBAY-SOA-SECURITY-TOKEN header and value.

This header supports the use of OAuth tokens for user authorization. To authorize the request, supply a valid User access token for the value to this header. For details on User access tokens, see OAuth access tokens
X-EBAY-SOA-SECURITY-TOKEN X-EBAY-SOA-SECURITY-TOKEN Conditionally Required if you do not supply an X-EBAY-SOA-SECURITY-IAFTOKEN header and value.

This header supports eBay Auth'n'Auth for user authorization. To authorize a request, pass a valid eBay Authorization token as the value to this header. For more on Authorization tokens, see Getting Tokens.
X-EBAY-SOA-SERVICE-VERSION X-EBAY-SOA-SERVICE-VERSION No The API version your application supports (e.g., 1.1.0).

URL Parameter Examples

If you are using a URL (and the HTTP GET method), input must be in the NV (Name-Value Pair) format. Use the RESPONSE-DATA-FORMAT header to specify that data is returned in one of the following formats: NV or XML. The following example (wrapped for readability) shows standard Business Policies Management API parameters. RESPONSE-DATA-FORMAT specifies XML for XML output.

https://svcs.ebay.com/services/selling/v1/SellerProfilesManagementService
  ?X-EBAY-SOA-OPERATION-NAME=getSellerProfiles
  &X-EBAY-SOA-SERVICE-NAME=SellerProfilesManagementService
  &X-EBAY-SOA-SERVICE-VERSION=1.0.0
  &X-EBAY-SOA-SECURITY-TOKEN=<eBayAuthToken>
  &X-EBAY-SOA-RESPONSE-DATA-FORMAT=XML
  &REST-PAYLOAD
  &Standard input fields
  &Call-specific input fields

HTTP Header Examples

The following example shows standard Business Policies Management API headers for an HTTP POST call using XML:

X-EBAY-SOA-SERVICE-NAME: SellerProfilesManagementService
X-EBAY-SOA-OPERATION-NAME: getSellerProfiles
X-EBAY-SOA-SERVICE-VERSION: 1.0.0
X-EBAY-SOA-SECURITY-TOKEN: <eBayAuthToken>
X-EBAY-SOA-REQUEST-DATA-FORMAT: XML

The following example shows standard Business Policies Management API headers for an HTTP POST call. In the example, the X-EBAY-SOA-REQUEST-DATA-FORMAT header specifies XML. The example also includes X-EBAY-SOA-MESSAGE-PROTOCOL: SOAP12, specifying that you are using SOAP Version 1.2. Without the X-EBAY-SOA-MESSAGE-PROTOCOL header, the service would expect XML input.

X-EBAY-SOA-SERVICE-NAME: SellerProfilesManagementService
X-EBAY-SOA-OPERATION-NAME: getSellerProfiles
X-EBAY-SOA-SERVICE-VERSION: 1.0.0
X-EBAY-SOA-GLOBAL-ID: EBAY-US
X-EBAY-SOA-SECURITY-TOKEN: <eBayAuthToken>
X-EBAY-SOA-REQUEST-DATA-FORMAT: XML
X-EBAY-SOA-MESSAGE-PROTOCOL: SOAP12

Call-Specific Values

Refer to the Business Policies Management API Reference for the input and output fields supported by the Business Policies Management API calls.

Syntax

This section spells out the syntax requirements for the supported request and response formats. In most cases, the syntax for the various formats is standard and only the rules that aren't standard or are potentially tricky are explained.

UTF-8 Encoding for Special Characters

All parameter values should be encoded in UTF-8 format. UTF-8 is the default encoding for API requests.

Once the parameter value is UTF-8 encoded, it should be URL-encoded to take care of spaces and quotation marks (" ") and other characters in the string that are pertinent to the URL request.

When submitting requests in any format other than UTF-8, you must specify the message encoding with the MESSAGE-ENCODING URL parameter or the X-EBAY-SOA-MESSAGE-ENCODING HTTP header.

URL Encoding for String Values

Name-value requests must be constructed using the ASCII character-set only. Most ASCII characters (e.g., the numbers from 0-9 and the uppercase and lowercase English letters from A to Z) can be used as is. Some special characters, however, such as spaces, ampersands ("&") and quotation marks, must be encoded in URL requests when used in string values for fields.

Special characters that must be URL-encoded include (but are not limited to) characters used in URL request syntax, such as ampersands ("&"), the equals sign ("="), the pound sign ("#"), the "at" symbol ("@"), or the percent sign ("%").

URL-encoded characters are in the form %HH, where HH is a hexadecimal number. For example, the URL-encoded value for an ampersand is %26 and the URL-encoded value for a space is %20. The plus sign ("+") can also be used in place of spaces.

Many languages provide functions or methods to do the URL encoding for you. For example, PHP provides the rawurlencode function and Java provides URLEncoder class. For more information about URL encoding, see RFC 1738.

XML Syntax

The XML request/response format follows standard XML syntax conventions. Please see XML Syntax Rules on w3schools.com for more information.

SOAP Syntax

The SOAP request/response format follows standard SOAP syntax conventions. Please see SOAP Syntax on w3schools.com for more information.

Schema Location

You can download the latest version of the WSDL for the Business Policies Management API with the following link:

    https://developer.ebay.com/webservices/business-policies/latest/SellerProfilesManagementService.wsdl

Alternatively, you can access a particular version of the Business Policies Management schema using a URL with the following format (where VERSION is the version identifier of the release):

   https://developer.ebay.com/webservices/business-policies/VERSION/SellerProfilesManagementService.wsdl

The version identifier is the version number of a particular schema (a release number).

For example, you can access version 1.0.0 of the WSDL version of the schema at the following URL:

    https://developer.ebay.com/webservices/business-policies/1.0.0/SellerProfilesManagementService.wsdl

Back to top