About the Pool Definition Items API

The Pool Definition Items API allows you to manage which catalog items are assigned to the benefits of a pool definition, a template that defines what subscribers get under a Pricing Plan. Benefits are the specific things subscribers can access within a pool definition, each identified by a benefitKey. Use this API together with other Wix Benefit Programs APIs. Learn more about benefit programs components and lifecycle.

With the Pool Definition Items API, you can:

• Add catalog items to a specific benefit in a pool definition.
• Remove items from a benefit.
• Query which items are assigned to which benefits.

Pool definition items in benefit programs

A pool definition item is the assignment of a catalog item to a benefit in a pool definition. The benefit is identified by a poolDefinitionId and benefitKey pair. There's 1 pool definition item for each combination of pool definition and item.

When items are added to or removed from a benefit, the change also applies to the pools of beneficiaries enrolled in programs based on the pool definition.

Pool definition item lifecycle

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

• Pool definition items are created when an item is added to a benefit, for example by calling Add Items to Benefit. They're also created when a benefit is added to a pool definition, with 1 pool definition item for each item already assigned to that benefit's item set.
• Pool definition items are removed when the item is removed from the benefit or deleted, when the benefit is removed from the pool definition, or when the pool definition is deleted.

Query Pool Definition Items doesn't return removed pool definition items.

Managing items in a benefit

Use Add Items to Benefit to add catalog items to a benefit, and Remove Items from Benefit to remove them. Both methods require the poolDefinitionId and benefitKey that identify the target benefit. You can retrieve these values by calling Get Pool Definition or Query Pool Definitions.

These methods encapsulate the integration between the Items API and the Pool Definitions API. They create or delete the underlying items in the benefit's item set, and the corresponding pool definition items are then created or removed automatically.

When you call Add Items to Benefit, only the externalId and category fields of each item reference are taken from your request. The providerAppId, namespace, and itemSetId of the resulting pool definition item are always inherited from the benefit's configuration in the pool definition.

There's no limit on the total number of items that can be assigned to a single benefit. Each method call supports up to 100 items.

Both methods use a partial success model. An item that's already assigned to the benefit, or an item reference that doesn't match any assigned item, returns a per-item failure while the other items are processed. Check bulkActionMetadata for aggregate counts and each result's itemMetadata for individual outcomes.

Enrich pool definition items

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

Value	Populates	Includes
POOL_DEFINITION	poolDefinition	Pool definition display name, description, and credit configuration.
PROGRAM_DEFINITION	programDefinitions	Display name and description of each program definition.
BENEFIT	benefitInfo	Benefit display name, description, and credit price.
ITEM	itemInfo	Item display name.

Request only the enrichments you need. Each one adds lookups to the related entities. If the related data isn't available, the enrichment details may be omitted from the response. The base fields of each pool definition item, including the id and externalId of each program definition, are always returned.

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.
• To call Add Items to Benefit or Remove Items from Benefit, you need the poolDefinitionId and benefitKey of the target benefit. Retrieve these from the Pool Definitions API.
• Pool definition items are created and removed asynchronously. Newly added items may take a short time to appear in Query Pool Definition Items results, and removed items may briefly still appear.
• To look up all pool definition items for a specific catalog item, for example to check which benefits a product has been added to, filter Query Pool Definition Items by itemSearchKey. This is a pre-computed field with the format providerAppId/category/externalId, which you can construct yourself. Filtering by itemSearchKey is more efficient than filtering by providerAppId, category, and externalId in 3 separate conditions.

Use cases

• Add catalog items to a benefit
• Query items assigned to a benefit
• Find all benefits a specific item is assigned to

Terminology

• Pool definition item: An assignment of a catalog item to a benefit in a pool definition.
• Item: A reference to a product, service, or content object provided by a 3rd-party app. Identified by a combination of providerAppId, category, and externalId.
• Benefit: A specific thing subscribers can access within a pool definition. Each benefit is identified by a benefitKey.
• Benefit key: A string defined by the provider when configuring a pool definition's benefits. Use it together with poolDefinitionId to identify the target benefit when calling Add Items to Benefit or Remove Items from Benefit.
• Category: A label used to group items by type in a provider app, for example class or booking. Defaults to an empty string if not specified.
• Item search key: A pre-computed field that uniquely identifies a catalog item in a provider app. Formed by joining providerAppId, category, and externalId with /. Use it as a single filter field when querying pool definition items by item search key.