About the Ribbons API

The Ribbons API allows you to create and manage ribbons, which can then be assigned to products using the Products API.

Ribbons are badges that highlight specific product features or promotions, such as "Sale", "New", "Bestseller", or custom labels.

With the Ribbons API, you can:

• Create and manage ribbons.
• Retrieve information about existing ribbons.
• Query ribbons with filtering and sorting.

Assigning ribbons to products

A product can be assigned a single primary ribbon through the product's ribbon field, and up to 4 additional ribbons through the product's additionalRibbons field. The primary ribbon and any additional ribbons are displayed together on product cards and on the product page.

You can assign a ribbon to a product by:

• Passing the ribbon's id when creating or updating a product.
• Passing a ribbon name. If a ribbon with that name exists, it's assigned; otherwise, a new ribbon is created.

The same assignment rules apply to both ribbon and additionalRibbons.

A ribbon can be assigned to a product at most once. The same ribbon can't appear more than once in additionalRibbons, and a ribbon set as the primary ribbon can't also appear in additionalRibbons.

Deleting ribbons

When a ribbon is deleted, it's automatically removed from all products that reference it.

Before you begin

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

• The Wix user must install the Wix Stores app.

Use cases

• Create a product with a new ribbon
• Assign an existing ribbon to a product

Terminology

For a comprehensive glossary of Catalog V3 terms, see Terminology.