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.

To add catalog items to a benefit:

1. Call Get Pool Definition or Query Pool Definitions to retrieve the poolDefinitionId and benefitKey for the target benefit.
2. 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.
3. Call Add Items to Benefit, 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.
4. 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.
5. Optionally, call Query Pool Definition Items 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 or Query Pool Definitions.
2. Call Query Pool Definition Items 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.
3. 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".
2. Call Query Pool Definition Items 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.
3. 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.