> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Introduction

## Article: Introduction

## Article Link: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/promotions-v3/introduction.md

## Article Content:

# 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](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories.md). 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](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/promotions-v3/resolve-promotions.md).

## 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](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/promotions-v3/bulk-update-promotion-tags.md) to assign or unassign tags on specific promotions, or [Bulk Update Promotion Tags By Filter](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/promotions-v3/bulk-update-promotion-tags-by-filter.md) 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](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/promotions-v3/sample-flows.md#sync-promotions-to-an-external-content-management-system)
- [Assign seasonal promotions to multiple categories](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/promotions-v3/sample-flows.md#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.

@sdk_package_setup