Get promotion — sell-marketing

v1

latestOpenAPI 3.0.0eBay API License Agreement2026-07-1469127536.5 KB

promotion

This method returns a list of a seller's undeleted promotions. The call returns up to 200 currently-available promotions on the specified marketplace. While the response body does not include the promotion's discountRules or inventoryCriterion containers, it does include the promotionHref (which you can use to retrieve the complete details of the promotion). Use query parameters to sort and filter the results by the number of promotions to return, the promotion state or type, and the eBay marketplace. You can also supply keywords to limit the response to the promotions that contain that keywords in the title of the promotion. Maximum returned: 200

get/promotion

Query parameters

limitstring

Specifies the maximum number of promotions returned on a page from the result set. Default: 200 Maximum: 200

marketplace_idstring required

The eBay marketplace ID of the site where the promotion is hosted. Valid values: <ul><li><code>EBAY_AU</code> = Australia</li> <li><code>EBAY_DE</code> = Germany</li> <li><code>EBAY_ES</code> = Spain</li> <li><code>EBAY_FR</code> = France</li> <li><code>EBAY_GB</code> = Great Britain</li> <li><code>EBAY_IT</code> = Italy</li> <li><code>EBAY_US</code> = United States</li></ul>

offsetstring

Specifies the number of promotions to skip in the result set before returning the first promotion in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of <code>0</code> and a limit of <code>10</code>, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is <code>10</code> and limit is <code>20</code>, the first page of the response contains items 11-30 from the complete result set. Default: 0

promotion_statusstring

Specifies the promotion state by which you want to filter the results. The response contains only those promotions that match the state you specify. Valid values: <ul><li><code>DRAFT</code></li> <li><code>SCHEDULED</code></li> <li><code>RUNNING</code></li> <li><code>PAUSED</code></li> <li><code>ENDED</code></li></ul>Maximum number of input values: 1

promotion_typestring

Filters the returned promotions based on their campaign promotion type. Specify one of the following values to indicate the promotion type you want returned: <ul><li><code>CODED_COUPON</code> – A coupon code promotion set with createItemPromotion.</li> <li><code>MARKDOWN_SALE</code> – A markdown promotion set with createItemPriceMarkdownPromotion.</li> <li><code>ORDER_DISCOUNT</code> – A threshold promotion set with createItemPromotion.</li> <li><code>VOLUME_DISCOUNT</code> – A volume pricing promotion set with createItemPromotion.</li></ul>

qstring

A string consisting of one or more keywords. eBay filters the response by returning only the promotions that contain the supplied keywords in the promotion title. Example: "iPhone" or "Harry Potter." Commas that separate keywords are ignored. For example, a keyword string of "iPhone, iPad" equals "iPhone iPad", and each results in a response that contains promotions with both "iPhone" and "iPad" in the title.

sortstring

Specifies the order for how to sort the response. If you precede the supplied value with a dash, the response is sorted in reverse order. Example: <code>sort=END_DATE</code> Sorts the promotions in the response by their end dates in ascending order <code>sort=-PROMOTION_NAME</code> Sorts the promotions by their promotion name in descending alphabetical order (Z-Az-a) Valid values:<ul><li><code>START_DATE</code></li> <li><code>END_DATE</code></li> <li><code>PROMOTION_NAME</code></li></ul> For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/marketing/types/csb:SortField

Response

Success

hrefstring

The URI of the current page of results from the result set.

limitinteger

The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.

nextstring

The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set. Max length: 2048

offsetinteger

The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of <code>0</code>.

prevstring

The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set. Max length: 2048

totalinteger

The total number of items retrieved in the result set. If no items are found, this field is returned with a value of <code>0</code>.