About the Program Categories API

The Program Categories API manages reusable, site-level classifications for Online Programs. A Category exists independently of any Program, can be assigned to many Programs, and remains available when it has no assignments.

Use this API from authorized owner-facing or backend app flows. For visitor- or member-facing catalogs, query the Programs API by categoryIds so that Program visibility and access rules are applied.

With the Program Categories API, you can:

• Create, retrieve, rename, and delete Categories.
• Assign or unassign Categories for a Program.
• Store namespaced app data in extendedFields.
• Read localized Category labels.

Category assignments

For routine assignment changes, call Bulk Assign Categories to Program. The operation updates each Category's assignedTo list and asynchronously synchronizes the Program's categoryIds list. Assignment changes are eventually consistent across the two APIs, so an immediate Programs API read may briefly return the previous state.

Assignments persist when a Program is published, ended, or archived. Unassigning the final Program leaves the Category intact. Deleting a Category is different: it removes the reusable taxonomy item globally and asynchronously removes its ID from every associated Program.

The current contract supports up to 200 Program IDs in one Category. The intended limit is 10 Category IDs in one Program. Bulk Assign Categories to Program checks that limit on a best-effort basis. Direct writes to assignedTo through Create Category, Bulk Create Categories, or Update Category bypass the check; callers using them must keep each Program at or below 10 Categories.

Category lifecycle webhooks

Category lifecycle events let an app keep its own Category records synchronized:

Event	When it is triggered	How to handle it
Category Created	A Category is created, including each successful item in Bulk Create Categories.	Read the Category from createdEvent.entity.
Category Updated	A Category is updated, including changes to its label or Program assignments.	Read the updated Category from updatedEvent.currentEntity.
Category Deleted	A Category is deleted.	Use entityId to remove the Category from your app's records.

The webhook JSON examples are illustrative and derived from the event schema. They show decoded event data; their event IDs, timestamps and sequence values are examples, not captured deliveries.

The events use the entity FQDN wix.achievements.categories.v3.category and the slugs created, updated, and deleted. The Manage Online Programs permission scope includes the Category read permission required for these events.

Use the event's id to recognize duplicate events. Receiving a Category event does not mean the related Program's categoryIds has finished synchronizing. After a deletion, removal of the Category ID from associated Programs also completes asynchronously.

Labels and localization

The primary-language label must be unique within the site and can contain up to 100 characters. Renaming a Category preserves its ID and Program assignments. Pass the current revision when updating it.

Localized reads return a Wix Multilingual translation when one is available and otherwise fall back to the primary label. Use Wix Multilingual to edit secondary-language values; Create Category and Update Category write the primary-language label.

Extended fields

Register extended-field schemas for wix.achievements.categories.v3.category. Extended field values don't affect assignments and aren't supported as server-side Query Categories filters.

Before you begin

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

• A site can contain up to 100 Categories. Use List Categories with no IDs to retrieve the full collection.
• Primary-language labels must be unique within the site.
• Use Bulk Assign Categories to Program for routine assignment changes. Don't include the same Category ID in both request lists, and check each result for failures.
• Allow for asynchronous synchronization when reading Program assignments after a change.
• Query Categories supports filtering and sorting by id.

Use cases

The sample flows show how to reuse site Categories, classify Programs, handle partial bulk results, and build a public catalog. They also explain how Program duplication carries over Category assignments.