> 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: Sample Flows

## Article: Sample Flows

## Article Link: https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/pool-definition-items/sample-flows.md

## Article Content:

# Pool Definition Items API: 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.

## Add catalog items to a benefit

A 3rd-party provider app, for example a fitness platform, wants to make specific items, such as yoga classes, available to subscribers of a Pricing Plan. To do this, the provider adds those items to the appropriate benefit in a pool definition.

> **Prerequisite:** You must have already created a pool definition with the relevant benefits using the [Pool Definitions API](https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/pool-definitions.md). Each benefit has a `benefitKey` set by your app.

To add catalog items to a benefit:

1. Call [Get Pool Definition](https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/pool-definitions/get-pool-definition.md) or [Query Pool Definitions](https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/pool-definitions/query-pool-definitions.md) to retrieve the `poolDefinitionId` and `benefitKey` for the target benefit.
1. Build a list of item references, each with the `externalId` of the catalog item in your system. Include a `category` if your app uses categories to group item types.
1. Call [Add Items to Benefit](https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/pool-definition-items/add-items-to-benefit.md), passing `poolDefinitionId`, `benefitKey`, and the list of item references. You can include up to 100 items per call. For larger catalogs, split the items into batches and make multiple calls.
1. Check `bulkActionMetadata.totalFailures` in the response. For each failed result, use `itemMetadata.originalIndex` to find the item reference in your request and `itemMetadata.error` to see why it failed. For example, the item may already be assigned to the benefit.
1. Optionally, call [Query Pool Definition Items](https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/pool-definition-items/query-pool-definition-items.md) filtered by `poolDefinitionId` and `benefitKey` to confirm the items were added. Pool definition items are created asynchronously, so newly added items may take a short time to appear.

The items are now accessible to subscribers enrolled in programs based on this pool definition.

## Query items assigned to a benefit

A provider app wants to sync its catalog with a Pricing Plan's benefits, for example to show a site owner which classes are included in a plan. The app queries pool definition items to retrieve the full list of items assigned to a specific benefit.

To query items assigned to a benefit:

1. Determine the `poolDefinitionId` and `benefitKey` for the benefit you want to inspect. You can retrieve these by calling [Get Pool Definition](https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/pool-definitions/get-pool-definition.md) or [Query Pool Definitions](https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/pool-definitions/query-pool-definitions.md).
1. Call [Query Pool Definition Items](https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/pool-definition-items/query-pool-definition-items.md) with a filter on `poolDefinitionId` and `benefitKey`. To include the item display names and benefit pricing, pass `["ITEM", "BENEFIT"]` in the `fields` parameter. Use cursor paging to retrieve all results when the response includes more than 1 page.
1. Use the returned `externalId`, `category`, and `providerAppId` fields to look up the corresponding catalog items in your app's system.

## Find all benefits a specific item is assigned to

A provider app wants to check which benefits a particular catalog item, for example a specific fitness class, has been added to. This is useful when syncing catalog changes, auditing benefit assignments across pool definitions, or showing which plans give access to an item.

To find all benefits a specific item is assigned to:

1. Construct the `itemSearchKey` for your item by joining its `providerAppId`, `category`, and `externalId` with `/`. For example: `"a1c7e2f4-3b5d-4e8a-9c6f-2d4b8e1a7c35/classes/7f3e9b21-4c8a-4d6e-b5f2-9a1c3e7d8b40"`.
1. Call [Query Pool Definition Items](https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/pool-definition-items/query-pool-definition-items.md) with a filter on `itemSearchKey`. To include the names of the plans that give access to the item, pass `["PROGRAM_DEFINITION"]` in the `fields` parameter. Use cursor paging to retrieve all results.
1. Use the `poolDefinitionId` and `benefitKey` of each returned pool definition item to identify the pool definition and benefit the item is assigned to, and `programDefinitions` to identify the plans that include that pool definition.