Program Categories: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Create or reuse categories

An app can reuse the site's existing Categories before creating the labels it needs. To resolve labels to Category IDs:

1. Call List Categories with no categoryIds and set x-wix-linguist to the site's primary-language context (<languageCode>|<locale>|true|<instanceId>). The response contains all site Categories, up to 100.
2. Match the primary-language labels your app needs. Labels are unique within the site.
3. Call Create Category or Bulk Create Categories only for missing labels.
4. For Bulk Create Categories, check each results[].itemMetadata.success. Use itemMetadata.originalIndex to match the result to the input, and handle itemMetadata.error for failures.
5. If bulkActionMetadata.undetailedFailures is greater than zero, call List Categories again with no categoryIds and the same primary-language context. Compare original input labels without item details against the complete response. Reuse the ID of each matching Category and retry only inputs whose labels are still absent.
6. Save itemMetadata.id only for successful bulk results and the IDs found by label in the reconciliation read. For Create Category, save the returned category.id. Use IDs, rather than labels, for Program assignments.

Classify a new program

Create a Program, then assign its Categories. To prepare the Program:

Part 1: Create the program

1. Call the Programs API to create the Program.
2. Save the returned Program ID.
3. Keep the Program's resulting Category set at or below 10 IDs.

Part 2: Assign categories

Use the Program ID and the Category IDs from the previous steps:

1. Call Bulk Assign Categories to Program with the Program ID and the Category IDs in categoriesToAssign.
2. Don't include an ID in both categoriesToAssign and categoriesToUnassign.
3. Check each results[].itemMetadata.success and match its itemMetadata.id to the requested Category ID. A successful response can contain both successful and failed assignments.
4. Handle itemMetadata.error for failed items. If bulkActionMetadata.undetailedFailures is greater than zero, use Get Category to check the assignedTo value for unresolved IDs before retrying.
5. Wait for asynchronous synchronization with the Programs API only for successfully processed Category IDs. An immediate Programs API read may return the previous categoryIds value, so retry the read rather than resubmitting a successful assignment or unassignment. Handle failed IDs separately.

Change a program's classification

An app can add and remove assignments in one request. After previous assignment changes have synchronized:

1. Compare the desired Category IDs with the Program's current categoryIds.
2. Put new IDs in categoriesToAssign and removed IDs in categoriesToUnassign.
3. Call Bulk Assign Categories to Program again and check each result as described above before waiting for synchronization.
4. To rename a Category, call Update Category with its current revision. The stable Category ID keeps Program relationships intact.

Remove a category

A site owner can remove a Category from one Program or delete it across the site. Choose the operation that matches their intent:

1. To remove a Category from one Program, call Bulk Assign Categories to Program with its ID in categoriesToUnassign. Check the per-item result before waiting for synchronization.
2. To delete the reusable Category from the site, call Delete Category. Deletion asynchronously removes the Category ID from all associated Programs.

Duplicate a program with category assignments

Duplicating a Program uses Bulk Assign Categories to Program to assign the original Program's Category IDs to the new Program. It reuses the existing Categories. To check the copied assignments:

1. Duplicate the Program through the Programs API and save the new Program's ID and the original Category IDs.
2. Retrieve each original Category with Get Category and check whether its assignedTo includes the new Program ID. The duplicated Program copies categoryIds, so that field alone doesn't confirm that each Category was updated.
3. For an assignment that remains absent, call Bulk Assign Categories to Program and check the per-item result. A successful duplication response alone doesn't confirm that every Category assignment succeeded.

Build a public catalog

For a visitor- or member-facing category page, retrieve Programs with the Programs API so that Program visibility and access rules are applied. To load the page:

1. Use the Category ID selected for the page.
2. Query the Programs API with a filter on categoryIds and the visitor or member identity.
3. Display the returned Programs. Category.assignedTo doesn't apply Program visibility and access rules and must not be used as a public catalog.