> 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-management/online-programs/categories/introduction.md

## Article Content:

# 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](https://dev.wix.com/docs/api-reference/business-management/online-programs/categories/bulk-assign-categories-to-program.md). 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](https://dev.wix.com/docs/api-reference/business-management/online-programs/categories/list-categories.md) 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](https://dev.wix.com/docs/api-reference/business-management/online-programs/categories/query-categories.md) supports filtering and sorting by `id`.

## Use cases

The [sample flows](https://dev.wix.com/docs/api-reference/business-management/online-programs/categories/sample-flows.md) 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.

@sdk_package_setup