This topic describes the basics of creating and managing a Promotions Manager discount promotion.

Promotions Manager promotion types

As described in Discount Promotion types, there are two fundamental types of Promotions Manager promotions:

  • Markdown promotions – Straight-forward discounts on existing listings.
  • Threshold promotions – Includes Volume Pricing, BOGO, and other types of discounts where the buyer must meet a preset criteria, or threshold, before the discount is given.

The flow chart below describes the method you use to create the type of promotion you want to run:

Note: When you create a promotion, the URI to the newly created promotion is returned in the Location response header. This value includes the promotion ID value, which is used in other Promotion Manager calls.

Creating and managing markdown promotions

Call createItemPriceMarkdownPromotion and specify the following required fields to create a new markdown promotion:

  • The marketplace on which the promotion runs
  • The item(s) to include in the promotion
  • The discount associated with the promotion
  • The start and end dates for the promotion

Customize your promotions by adding images, seller-specified labels, and a priority as they relate to other active promotions, and preview them before making them active by creating the promotion in a DRAFT state.

Once you've created a promotion, manage and update it using the markdown promotion methods in the Marketing APII. The following table lists all the calls specific to markdown promotions:

Markdown Promotion Methods Description
createItemPriceMarkdownPromotion Creates a markdown promotion.
getItemPriceMarkdownPromotion Retrieves the details of a single markdown promotion.
updateItemPriceMarkdownPromotion Updates a markdown promotion.
deleteItemPriceMarkdownPromotion Deletes a markdown promotion.

Creating and managing threshold promotions

Call createItemPromotion and specify the following required fields to create a new threshold promotion:

  • The marketplace on which the promotion runs
  • The item(s) to include in the promotion
  • The discount associated with the promotion
  • The discount threshold, or when the discount "triggers"
  • The start and end dates for the promotion

Customize your promotions by adding images, seller-specified labels, and a priority as they relate to other active promotions, and preview them before making them active by creating them in a DRAFT state.

Once you've created a promotion, manage and update it using the item promotion methods in the Marketing API. The following table lists all the calls specific to threshold promotions:

Threshold Promotion Methods Description
createItemPromotion Creates an threshold promotion.
getItemPromotion Retrieves the details of a single threshold promotion.
getPromotions Retrieves the list of threshold promotions offered by a seller.
updateItemPromotion Updates a threshold promotion.
deleteItemPromotion Deletes a threshold promotion.

Specifying the items to include in a promotion

Whether you are configuring a markdown promotion or a threshold promotion, there are two ways to specify the listings to include in the promotion:

  • Key-based promotions – Select the listings you want to promote using either listing IDs or inventory reference IDs.
  • Rule-based promotions – Select the listings you want to promote using a set of criteria, or rules, that the seller defines.

You specify the items to include in a promotion when you create a promotion with a call to either createItemPriceMarkdownPromotion or createItemPromotion. Both methods use the same structure to include listings, and you use either the key-based values or the rule-based values in the create call to specify the listings you want to include in the promotion.

When the Promotions Manager includes a listing in a promotion, the service creates the "offer-type text" for the listing, which is an eBay-generated, non-editable tag line for the discount. The offer-type text is displayed with the listing in the eBay buyer flows.

Configuring key-based promotions

Specify items to include in key-based promotions using either the listingIds or inventoryItems containers in your call to createItemPriceMarkdownPromotion or createItemPromotion:

  • listingIds – Use listing ID values generated by the Trading API or the Inventory API to specify the listings you want to promote.
  • inventoryItems – You can use inventoryReferenceId and inventoryReferenceType values to specify the items you want to include in a promotion if you manage your inventory with the Inventory API.

    An inventoryReferenceId is either a seller-defined SKU value or an inventoryItemGroupKey (a seller-defined ID for a multiple-variation listing). To indicate a listing is managed by the Inventory API, you must always specify both an inventoryReferenceId and its associated inventoryReferenceType, where the inventoryReferenceType is set to either INVENTORY_ITEM or INVENTORY_ITEM_GROUP depending on the item type being referenced.

The following snippet shows the structure of the inventoryCriterion container where you specify which listings to promote. Set inventoryCriterionType to INVENTORY_BY_VALUE, then populate either the inventoryItems or listingIds field, depending on how you want to specify your listings:

{
  "inventoryCriterion": {
    "inventoryCriterionType": "INVENTORY_BY_VALUE",
    "inventoryItems": [
      {
        "inventoryReferenceId": "string",
        "inventoryReferenceType": "[INVENTORY_ITEM || INVENTORY_ITEM_GROUP ]"
      }
    ],
    "listingIds": [ "string" ]
  }
}

Note: You can include a maximum of 500 IDs in any createItemPromotion or createItemPriceMarkdownPromotion request.

Configuring rule-based promotions

Specify items to include in rule-based promotions using the selectionRules containers in your call to createItemPriceMarkdownPromotion or createItemPromotion.

All the fields in the selectionRules container are optional, and you can configure up to 10 distinct selectionRules elements in a call, where each container identifies a set of criteria for the listings to include in the promotion.

The following snippet shows the structure of the inventoryCriterion container where you specify which listings to promote using rules. Set inventoryCriterionType to INVENTORY_BY_RULE, then populate the selectionRules container:

{
  "inventoryCriterion": {
    "inventoryCriterionType": "INVENTORY_BY_RULE",
    "ruleCriteria": {
      "selectionRules": [
        {
          "brands": [ "string" ],
          "categoryIds": [ "string" ],
          "categoryScope": "[ MARKETPLACE || STORE ]",
          "listingConditionIds": [ "string" ],
          "maxPrice": { ... },
          "minPrice": { ... }
        }
      ]
    }
  }
}

In each selectionRules element, configure the following fields to identify the listings you want to promote:

  • brands – A list of brands to include in the promotion. A discounted listing is created for a listing if its brand matches one of the names identified in this rule.
  • categoryIds – A list of category IDs, which can contain either category IDs from the associated marketplace or category IDs from the seller's store.
  • categoryScope – A value that identifies the type of category IDs used in this set of rules, either MARKETPLACE or STORE.
  • listingConditionIds – A list of numeric values that indicates the condition of the items to include in the promotion. See the Marketing API Reference for details on allowed values.
  • maxPrice – With all other rules considered, the price of a listing cannot exceed this amount for it to be included in the promotion.
  • minPrice – With all other rules considered, the price of a listing cannot be lower than this amount for it to be included in the promotion.

For example:

{
  "selectionRules": [
      {
        "brands": [ "list", "of", "brands"
        ],
        "categoryIds": [ "324490516", "324480516"
        ],
        "categoryScope": "STORE",
        "listingConditionIds": [ "300"
        ],
        "minPrice": {
          "currency": "USD",
          "value": "95.95"
        }
      }
    ]
  }

Note: The selection rules you create can include a maximum of 10k listings in any createItemPriceMarkdownPromotion request. However, there is no limit to the number of listings you can include in a promotion created with createItemPromotion.

Excluding specific listings

When creating a rule-based promotion, you can explicitly exclude up to 100 listings from the promotion. A promotion can have multiple rules, however exclusions are limited to a maximum of 100 parent items when entering inventory item IDs or listing IDs, or when choosing from live inventory.

You can specify IDs to exclude from a promotion using either:

  • listingId values – As used by either the Trading API or the Inventory API.
  • inventoryReferenceId values – As used by the Inventory API.
{
  "inventoryCriterion": {
    "inventoryCriterionType": "INVENTORY_BY_RULE",
    "ruleCriteria": {
      "excludeInventoryItems": [
        {
          "inventoryReferenceId": "string",
          "inventoryReferenceType": "[ INVENTORY_ITEM || INVENTORY_ITEM_GROUP ]"
        }
      ],
      "excludeListingIds": [ "string" ]
    }
  }
}

Methods shared across promotion types

There are several methods that support both markdown promotions and threshold promotions. These methods let you pause and restart promotions, get promotion reports, and get the set of items that are included in any one promotion:

General Promotions Manager Methods Description
getListingSet Retrieves the items associated with a promotion.
pausePromotion Pauses a running promotion.
resumePromotion Resumes a paused promotion.
getPromotionReports Retrieves a report on completed promotions.
getPromotionSummaryReport Retrieves a Summary Report for a specific promotion.

Promotions and marketplaces

All promotions configured with Promotions Manager are site-specific and you can add an item to a promotion only if the item is listed on the site where the promotion is running.

For example, after the seller has accepted the US terms and conditions, they can create a promotion for any of their inventory that's currently active on EBAY-US (ebay.com). The promotion shows up only on ebay.com, even if the items can be shipped to another country (such as Australia). To create a promotion for domestic Australian buyers on EBAY-AU (ebay.com.au), the seller needs to accept the Australian terms and conditions and create the promotion on ebay.com.au. They can then add items currently listed on ebay.com.au to that promotion.

Promotion states

The promotionStatus can be set to several states. When you first create a promotion, you must set the promotionStatus to either DRAFT or SCHEDULED. Use the DRAFT state when you're initially creating a promotion and you want to be sure it's correctly configured before setting it to SCHEDULED.

When you set the promotion to SCHEDULED, the promotion will begin to run at the configured startDate, and the status will then be set to RUNNING. When the endDate of the promotion is reached, the state is set to ENDED.

The flow chart below details valid sequence of promotionStatus states:

Flow of promotionStatus states
The sequence of promotionStatus states