Pool 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.

Show a member their currently accessible items

A member-facing site or app wants to display all the items the logged-in member can currently access. For example, a "Your benefits" page that lists the products, classes, or content unlocked by the member's active subscriptions.

To show a member their currently accessible items:

1. Call Query Pool Items from the member's session, with no beneficiary filter. The response is automatically scoped to the calling member.
2. To include human-readable details for each item, pass ["BENEFIT", "ITEM"] in the fields parameter. This returns the benefit name, item display name, and credit price (when configured) alongside the base fields. Add "BALANCE" to show how many credits the member has left. For all available values, see Enrich pool items.
3. Use cursor paging to retrieve all results when the response includes more than the default page size.
4. Group the returned pool items by programId or poolId in your UI to surface which subscription each item belongs to.

If your app calls the method from a backend (not a member session), include an explicit beneficiary.memberId filter to scope the response to a specific member.

Check whether a member can access a specific catalog item

A provider app wants to verify that a member can access a specific catalog item, for example before letting them book a yoga class or download a digital product. Rather than walking the program → pool → benefit → item chain, query pool items directly by the item's source-catalog reference.

To check whether a member can access a specific catalog item:

1. Construct the itemSearchKey for the catalog item by joining its providerAppId, category, and externalId with /. For example: "app-456/class/abc-123".
2. Call Query Pool Items with a filter on itemSearchKey and a filter on the member's identity (beneficiary.memberId).
3. Check the poolItems array in the response. At least 1 pool item means the member can access the item through 1 of their active programs, and each returned pool item carries the poolId, programId, and benefitKey that grant the access. An empty array means the member can't currently access the item, either because they aren't enrolled in a program that grants it or because the access was already removed.

List all items in a specific benefit for a member

A subscriber-facing app wants to show all items associated with a specific benefit that a member can access, for example the products included in a "10% off" benefit attached to the member's plan.

To list all items in a specific benefit for a member:

1. Determine the poolId and benefitKey for the benefit you want to inspect. You can retrieve the relevant pool by calling Query Pools filtered by the member's beneficiary identity. Each pool surfaces its benefits and their benefitKey values.
2. Call Query Pool Items with a filter on poolId and benefitKey. Add a beneficiary.memberId filter if your app is calling from a backend.
3. To enrich the response with item display names and benefit pricing, pass ["ITEM", "BENEFIT"] in the fields parameter.
4. Use the returned externalId, category, and providerAppId fields to look up each item's full details in the provider's catalog (for example, fetch product details from Wix Stores).

Use cursor paging to retrieve all results when the response includes more than the default page size.