This document explains how to make Order Size Discounts API calls. It provides an overview of the formats and parameters you can use with the Order Size Discounts API.
Order Size Discounts is a SOA service that is intended to be consumed by sellers in the US, UK, and Germany. This service allows sellers to create and manage discount campaigns. Discount campaigns allow sellers to offer discounts to buyers based on order size (number of items in order or total order value). To be eligible for a discount, buyers must purchase the primary product and at least one related item in a product bundle. Product bundles assist sellers in increasing sales by marketing related items to buyers. The Order Size Discounts API has calls to create, update, retrieve, and delete discount campaigns. Additionally, the getVersion call simply returns the current version of the Order Size Discounts service.
v1). When updating to a new major version of the service, you must update to a new service endpoint as well.
X-EBAY-SOA-SECURITY-APPNAME) header or (
SECURITY-APPNAME) URL parameter.
For more information on the createCampaigns call, see the Users Guide.
For more information on the deleteCampaigns call, see the Users Guide.
For more information on the getCampaign call, see the Users Guide.
For more information on the getCampaigns call, see the Users Guide.
For more information on the setCampaignStatus call, see the Users Guide.
For more information on the updateCampaigns call, see the Users Guide.
For more information on the getVersion call, see the Users Guide.
The Order Size Discounts API supports XML and SOAP request and response formats.
The HTTP POST call method supports the use of XML format requests.
<createCampaigns xmlns="http://www.ebay.com/marketplace/incentives/v1/services"> </createCampaigns>
The HTTP POST call method also supports the use of SOAP format requests. SOAP versions 1.1 and 1.2 are both supported.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope" xmlns="http://www.ebay.com/marketplace/incentives/v1/services"> <soap:Header/> <soap:Body> <createCampaigns> </createCampaigns> </soap:Body> </soap:Envelope>
The call response for SOAP requests is in SOAP format only.
Each Order Size Discounts API call consists of the following elements:
X-EBAY-SOA-SECURITY-APPNAMEheader or a
SECURITY-APPNAMEURL parameter. Similarly, you must always specify the call name in the
OPERATION-NAMEURL parameter. Other headers are optional or conditionally required.
Order Size Discounts API requests may be sent to either the eBay Production API Gateway URI (endpoint) or the eBay Sandbox endpoint. You specify the endpoint in the request.
|Note: The service endpoint contains the major version for the service (e.g.,
When you make a Order Size Discounts API call, you choose whether to specify the standard values in URL parameters or in the HTTP headers. 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 Order Size Discounts API parameters and the corresponding header values:
|URL Parameter||Header Value||Required?||Description|
|N/A||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:
|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.|
|SERVICE-NAME||X-EBAY-SOA-SERVICE-NAME||No||The name of the service you are using. Specify "SellerDiscountOfferManagementService" for all Order Size Discounts API calls.|
|OPERATION-NAME||X-EBAY-SOA-OPERATION-NAME||Yes||The name of the call you are using (for example, createCampaigns or getCampaigns).|
|REQUEST-DATA-FORMAT||X-EBAY-SOA-REQUEST-DATA-FORMAT||No||The Order Size Discounts 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
|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.|
|SECURITY-APPNAME||X-EBAY-SOA-SECURITY-APPNAME||Yes||This header is used to pass in the eBay authorization token, unique to the user's application. You obtain an eBay authorization token by joining the eBay Developer Network.|
|SERVICE-VERSION||X-EBAY-SOA-SERVICE-VERSION||No||The API version your application supports (e.g., 1.1.0).|
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 Order Size Discounts API parameters.
RESPONSE-DATA-FORMAT specifies XML
for XML output.
https://svcs.ebay.com/services/incentives/SellerDiscountOfferManagementService/v1?OPERATION-NAME=createCampaigns &SERVICE-NAME=SellerDiscountOfferManagementService &SERVICE-VERSION=1.0.0 &SECURITY-APPNAME=<eBayAuthToken> &RESPONSE-DATA-FORMAT=XML &REST-PAYLOAD &Standard input fields &Call-specific input fields
The following example shows standard Competitive Pricing API headers for an HTTP POST call using XML:
X-EBAY-SOA-SERVICE-NAME: SellerDiscountOfferManagementService X-EBAY-SOA-OPERATION-NAME: createCampaigns X-EBAY-SOA-SERVICE-VERSION: 1.0.0 X-EBAY-SOA-SECURITY-APPNAME: <eBayAuthToken> X-EBAY-SOA-REQUEST-DATA-FORMAT: XML
The following example shows standard Order Size Discounts API headers for an HTTP POST call. In 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: SellerDiscountOfferManagementService X-EBAY-SOA-OPERATION-NAME: createCampaigns X-EBAY-SOA-SERVICE-VERSION: 1.0.0 X-EBAY-SOA-GLOBAL-ID: EBAY-US X-EBAY-SOA-SECURITY-APPNAME: <eBayAuthToken> X-EBAY-SOA-REQUEST-DATA-FORMAT: XML X-EBAY-SOA-MESSAGE-PROTOCOL: SOAP12
Refer to the Order Size Discounts API Call Reference for the input and output fields supported by the Order Size Discounts API calls.
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.
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.
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.
The XML request/response format follows standard XML syntax conventions. Please see XML Syntax Rules on w3schools.com for more information.
The SOAP request/response format follows standard SOAP syntax conventions. Please see SOAP Syntax on w3schools.com for more information.
You can use the Sandbox environment (with the
http://svcs.sandbox.ebay.com/services/incentives/v1/SellerDiscountOfferManagementService endpoint) to test calls to the Order Size Discounts API.
You can download the latest version of the WSDL for the Order Size Discounts API with the following link:
Alternatively, you can access a particular version of the Order Size Discounts schema using a URL with the following format (where VERSION is the version identifier of the release):
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:
Back to top
© 2009–2012 eBay Inc. All rights reserved.
eBay and the eBay logo are registered trademarks of eBay Inc.
All other brands are the property of their respective owners.