About the Pool Items API

The Pool Items API lets you query which catalog items a member can access through their active benefit programs. Each pool item is a specific product, class, post, or other catalog item that's been provisioned for a member, contact, or visitor as part of a benefit in their pool. Use this API together with other Wix Benefit Programs APIs.

With the Pool Items API, you can:

• List a member's currently accessible items in a single query, without walking the Programs, Pools, and Items APIs yourself.
• Check whether a member can access a specific catalog item by its provider-app reference (for example, a Wix Stores product ID).
• List all items granted by a specific benefit for a specific member.
• Filter pool items by benefit, program, category, provider app, or any of the supported fields.

Pool items in benefit programs

A pool item is the per-beneficiary copy of a catalog item that's been assigned to a benefit inside a beneficiary's pool. Pool items collapse the multi-step lookup that the underlying APIs would otherwise require. Instead of querying Programs, then Pools, then Items and joining the results, a single Query Pool Items call returns the per-member list directly.

Each pool item carries a providerAppId, category, and externalId triple that identifies the underlying catalog item, such as a Wix Stores product or a Wix Bookings service. Use these fields, or the pre-computed itemSearchKey, to map a pool item back to its source catalog. itemSearchKey has the format providerAppId/category/externalId. You can construct it manually with a / separator. Filtering by itemSearchKey is more efficient than composing 3 separate filter conditions.

Learn more about benefit programs components and lifecycle.

Pool item lifecycle

You don't create, update, or delete pool items directly. They're kept in sync with the underlying pools and items:

• Pool items are created when a pool is provisioned for a beneficiary, with 1 pool item for each item in each of the pool's benefits. They're also created when an item is added to a benefit, in every pool that contains that benefit.
• Pool items are removed when the pool ends or is deleted, when the benefit is removed from the pool, or when the item is deleted.

There's a single pool item for each combination of pool and item. Query Pool Items doesn't return removed pool items.

Enrich pool items

By default, each pool item includes only IDs and item references. To include display details from the related entities, pass one or more values in the fields parameter of Query Pool Items:

Value	Populates	Includes
POOL	pool	Pool display name, description, status, and credit configuration.
PROGRAM	program	Program ID, display name, and external ID, if set.
PROGRAM_DEFINITION	programDefinition	Program definition ID, display name, description, and external ID, if set.
ITEM	itemInfo	Catalog item display name.
BENEFIT	benefitInfo	Benefit key, display name, description, and credit price.
BALANCE	balance	Pool's available credit balance.

Request only the enrichments you need. Each one adds lookups to the related entities.

Credits and benefit pricing

When you request the BENEFIT enrichment via the fields parameter, benefitInfo.price is populated with the cost to consume the benefit, expressed in credits. Credits are a configurable unit defined on the parent pool definition: each pool definition declares a credit configuration that includes a unit type. benefitInfo.price is absent when the benefit doesn't use credit-based pricing.

To check whether a member can afford a benefit, request the BALANCE and POOL enrichments. If pool.creditConfiguration is set, compare balance.available with benefitInfo.price. If it isn't set, the pool doesn't use credits: balance.available is 0, and benefits can be redeemed without a balance check.

Before you begin

It's important to note the following points before starting to code:

• Sites using this API must install the Pricing Plans app.
• Pool items are created and removed by the underlying Pools and Items services. Eventual consistency applies. Newly assigned items may take a short time to appear in Query Pool Items results.
• App callers must include an explicit beneficiary.memberId filter to scope results to a specific beneficiary. Member callers don't need this filter, as the response is automatically scoped to the calling member.

Use cases

• Show a member their currently accessible items
• Check whether a member can access a specific catalog item
• List all items in a specific benefit for a member

Terminology

• Pool item: The per-beneficiary copy of a catalog item assigned to a benefit inside a beneficiary's pool. Identifies the specific item that a specific beneficiary can access.
• Beneficiary: The member, contact, or visitor who holds a pool. Identified by the beneficiary field on each pool item.
• Benefit: A specific thing a beneficiary can access in a pool. Each benefit is identified by a benefitKey. Use poolId together with benefitKey to identify a benefit.
• Item set: An internal grouping identifier for a benefit's items. Surfaced as itemSetId on each pool item, but not the developer-facing identifier. Use poolId and benefitKey instead.
• Provider app: The 3rd-party app that supplies the underlying catalog item. Identified by providerAppId on each pool item.
• Category: A label that the provider app uses to group items by type, for example class, post, or group.
• Item search key: A pre-computed field that uniquely identifies a catalog item within a provider app. Formed by joining providerAppId, category, and externalId with /. Use it as a single filter field when querying pool items by item reference.
• Credit: A configurable unit defined on a pool definition's credit configuration. The unit type is set per pool definition (for example, point or token). Used in benefitInfo.price when the benefit has credit-based pricing.