About the Promotions API

The Promotions API allows you to create and manage visual banners displayed on store category pages, including their product gallery sections. Promotions can highlight sales, seasonal offers, or featured content and link site visitors to relevant pages.

With the Promotions API, you can:

• Create, update, and delete promotional banners.
• Assign promotions to store categories, with optional inheritance to subcategories.
• Retrieve the effective promotions for a category, accounting for position and conflict resolution.
• Search and query promotions with filtering, sorting, and free-text search.
• Manage promotions in bulk.

Category assignments

Each promotion can be assigned to one or more categories. Within each category, promotions are ordered by position, starting from 1. You can also set appliedToSubcategories to true for a category assignment, which makes the promotion appear in that category's subcategories with the same position.

When multiple enabled promotions apply at the same position in a category (either directly or through subcategory inheritance), the conflict is resolved based on the promotion's activation date. The activation date is the later of the promotion's creation date and the date it was last enabled. The promotion with the most recent activation date takes precedence.

To retrieve the resolved list of enabled promotions for a category, use Resolve Promotions.

Promotion media

Every promotion requires a media image. You can set the image using a Wix Media Manager file ID, or with an external URL. When you set media with a URL, Wix Media Manager imports the image asynchronously, and the promotion stays disabled until the import completes. If the import fails, the promotion's media is cleared and the promotion stays disabled. Once media is set on a promotion, it can be replaced but not removed.

Promotion tags

Assign public or private tags to promotions to organize and filter them. Use Bulk Update Promotion Tags to assign or unassign tags on specific promotions, or Bulk Update Promotion Tags By Filter to update tags asynchronously on all promotions matching a filter.

Limitations

• A site can have up to 100 promotions.

Before you begin

It's important to note the following points before starting to code:

• Promotions are created in a disabled state by default. Set enabled to true to make a promotion visible on the storefront.

Use cases

• Sync promotions to an external content management system
• Assign seasonal promotions to multiple categories

Terminology

• Promotion: A visual banner image displayed on store category pages, including their product gallery sections, optionally linking to a destination URL.
• Category assignment: The association between a promotion and a store category, including the promotion's display position and whether it applies to subcategories.
• Resolve: The process of determining which promotions are effective for a category, considering direct assignments, subcategory inheritance, and conflict resolution.
• Tag: A label assigned to a promotion for organizing and filtering. Tags can be public or private.