Creating discounts

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

Discount Manager discount types

As described in Discount types, there are two fundamental types of Discount Manager discounts:

• Markdown discounts – Straight-forward discounts on existing listings.
• Threshold discounts – 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 discount you want to run:

Creating and managing markdown discounts

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

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

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

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

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

Creating and managing threshold discounts

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

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

Customize your discounts 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 discount, manage and update it using the item promotion methods in the Marketing API. The following table lists all the calls specific to threshold discounts:

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

Specifying the items to discount

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

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

You specify the items to discount when you create the discount 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 discount.

When the Discount Manager includes a listing that is being discounted, 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 discounts

Specify items to include in key-based discounts 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 discount.

• inventoryItems – You can use inventoryReferenceId and inventoryReferenceType values to specify the items you want to discount 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 discount. 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" ]
  }
}

Configuring rule-based discounts

Specify items to include in rule-based discounts 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 discount.

The following snippet shows the structure of the inventoryCriterion container where you specify which listings to discount 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 discount:

• brands – A list of brands to include in the discount. 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 discount. 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 discount.
• minPrice – With all other rules considered, the price of a listing cannot be lower than this amount for it to be included in the discount.

For example:

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

Excluding specific listings

When creating a rule-based discount, you can explicitly exclude up to 100 listings from being discounted. A discount 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 discount 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 discount types

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

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

Discounts and marketplaces

All discounts configured with Discounts Manager are site-specific and you can add an item to be discounted only if the item is listed on the site where the discount is running.

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

Discount states

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

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

The flow chart below details valid sequence of promotionStatus states:

The sequence of promotionStatus states