MX Promotional Prices API Overview

Sellers can set regular or promotional prices for their items. Setting the Promotional prices is an option to create unique pricing for events such as clearance sales or to call out a comparison price.

The following rules apply to set the promotions:

The maximum number of promotions for a given item should not be more than 5.
The effective start date for a given promotion should be more than four hours from the current date and time.
You cannot cancel a promotion within four hours of the start time. If you want to cancel a promotion that is about to start, you should let it begin and then use the delete an item call.
You must provide SKU, startDate and endDate.
A promotion end date cannot be before or equal to the promotion start date.
The end date of a given promotion should be within 365 days from the current date and time. Any promotions beyond 365 days will result in an error.
If a promotion schedule is overlapping or the same as other promotions for the same item, it will result in an error.

The promotional price types are:

Clearance – Adds a Clearance badge, the price (the actual sale price) and a comparison price on the Item page.
Reduced – The same as Clearance, but with a Reduced badge on the Item page.

XSD attributes for setting up a promotion

Name	Description	Type	Required	Default
replaceAll	Replaces all previously set promotions for a SKU. To delete all promotions for a SKU, set replaceAll to an empty payload. Set replaceAll to false when using the processMode UPSERT or DELETE.	Boolean	Yes	true
effectiveDate	The effective start date for a given promotion	String	Yes	N/A
expirationDate	The end date for a given promotion. It should be no more than 365 days from the current date and time.	String	Yes	N/A
currentPrice	The current price for the item. If setting a promotion, set this value to the promotional price.	String	No	N/A
currentPriceType	The current price Type to indicate a promotion, such as REDUCED or CLEARANCE	String	No	N/A
comparisonPrice	The regular (BASE) or list price of the item. If a promotion is set up, this price may display as the ‘was’ price.	String	Yes	N/A
promoId	A system-generated ID for each promotion. Can be used to update or delete an existing promotion.	String	No	N/A
processMode	Use the processMode attribute to update or delete a promotion. To update a promotion for a SKU that includes multiple promotions, set the processMode to UPSERT and include a promoId. To delete a SKU, set the processMode to DELETE and include the promoId to be deleted. Additionally, a promotion can be updated or deleted by sending in a startDate and endDate for an SKU.	String	Yes	N/A
processModeType	Valid values are UPSERT or DELETE	String	No	N/A

XML & JSON schema files

You can download the Price schema files that contain attributes for Promotions. See XML Schema Files and JSON Schema Files sections in Price Management API Overview.

XSD attributes for setting up a promotion

XML & JSON schema files

See also