> 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 # QueryPoolDefinitionItems # Package: benefitPrograms # Namespace: PoolDefinitionItemService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/pool-definition-items/query-pool-definition-items.md ## Permission Scopes: Read benefit programs: SCOPE.BENEFIT_PROGRAMS.READ ## Introduction Retrieves a list of up to 1,000 pool definition items based on the specified paging, filtering, and sorting. To learn how to query pool definition items, see [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language). Pass 1 or more values in the `fields` parameter to populate additional data: - `POOL_DEFINITION`: Populates `poolDefinition` with the pool definition's display name, description, and credit configuration. - `PROGRAM_DEFINITION`: Populates `programDefinitions` with `displayName` and description. Use this field to show which plans grant access to a specified item. - `BENEFIT`: Populates `benefitInfo` with the benefit's credit price, display name, and description. - `ITEM`: Populates `itemInfo` with the catalog item's display name. Enrichment data is silently absent if the source data is unavailable. --- ## REST API ### Schema ``` Method: queryPoolDefinitionItems Description: Retrieves a list of up to 1,000 pool definition items based on the specified paging, filtering, and sorting. To learn how to query pool definition items, see [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language). Pass 1 or more values in the `fields` parameter to populate additional data: - `POOL_DEFINITION`: Populates `poolDefinition` with the pool definition's display name, description, and credit configuration. - `PROGRAM_DEFINITION`: Populates `programDefinitions` with `displayName` and description. Use this field to show which plans grant access to a specified item. - `BENEFIT`: Populates `benefitInfo` with the benefit's credit price, display name, and description. - `ITEM`: Populates `itemInfo` with the catalog item's display name. Enrichment data is silently absent if the source data is unavailable. URL: https://www.wixapis.com/benefit-programs/v1/pool-definition-items/query Method: POST Method parameters: param name: fields | type: array | description: Fields to be included in the response. - enum: - POOL_DEFINITION: Populates the `poolDefinition` field with display name, description, and credit configuration. - PROGRAM_DEFINITION: Populates the `programDefinitions` field with `displayName` and description. - BENEFIT: Populates the `benefitInfo` field with credit price, name, and description. - ITEM: Populates the `itemInfo` field with the catalog item's display name. param name: query | type: CursorQuery - name: cursorPaging | type: CursorPaging | description: Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not `filter` or `sort`. - name: limit | type: integer | description: Maximum number of items to return in the results. - name: cursor | type: string | description: Pointer to the next or previous page in the list of results. Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. - name: filter | type: object | description: Filter object in the following format: `"filter" : { "fieldName1": "value1", "fieldName2":{"$operator":"value2"} }` Example of operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, `$contains` - name: sort | type: array | description: Sort object in the following format: `[{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]` - name: fieldName | type: string | description: Name of the field to sort by. - name: order | type: SortOrder | description: Sort order. - enum: ASC, DESC Return type: QueryPoolDefinitionItemsResponse - name: poolDefinitionItems | type: array | description: List of items. - name: id | type: string | description: Benefit item GUID. Deterministically generated from pool_definition_id and item_id — if you know both, you can compute the GUID without querying. - name: revision | type: string | description: Revision number, which increments by 1 each time the benefit item is updated. - name: createdDate | type: string | description: Date and time the item was created. - name: updatedDate | type: string | description: Date and time the item was updated. - name: externalId | type: string | description: External item GUID assigned by the provider of the items. For example, if the benefit items are products, this GUID corresponds to the specific product GUID in the provider's system. - name: category | type: string | description: Item category. Groups benefit items together for organization and management purposes. For example, classes, posts, groups. - name: providerAppId | type: string | description: GUID of the application providing the benefit items. Each item's external_id is unique within its provider application. - name: namespace | type: string | description: Namespace for your app or site's benefit programs. Namespaces allow you to distinguish between entities that you created and entities that other apps created. - name: poolDefinitionId | type: string | description: GUID of the pool definition - the configuration that defines a set of benefits and which items are accessible within each benefit. - name: itemSetId | type: string | description: Internal grouping identifier for this benefit's item set. Use pool_definition_id together with benefit_key to identify a benefit — item_set_id is an implementation detail. - name: poolDefinition | type: PoolDefinitionInfo | description: Pool definition details including display name, description, and credit settings. Only populated when POOL_DEFINITION is included in the fields request parameter. - name: displayName | type: string | description: Pool definition name. - name: description | type: string | description: Pool definition description. - name: creditConfiguration | type: CreditConfiguration | description: Credit configuration for this pool definition. When absent, benefits in this pool do not support credit-based pricing. - name: amount | type: string | description: Number of credits initially granted to a subscriber when this pool definition's benefits are activated. - name: unitDisplayName | type: string | description: Credit unit display name. - name: unitType | type: string | description: Credit unit type. - name: programDefinitions | type: array | description: Program definitions that include this item as an accessible benefit. Only id and external_id are returned by default; request PROGRAM_DEFINITION to include display_name and description. - name: id | type: string | description: Program definition id - name: externalId | type: string | description: Program definition external id - name: displayName | type: string | description: Program definition name - name: description | type: string | description: Program definition description. - name: itemId | type: string | description: Item GUID. - name: benefitInfo | type: BenefitInfo | description: Pricing and display information for the associated benefit, including credit price, name, and description. Only populated when BENEFIT is included in the fields request parameter. - name: price | type: string | description: Price of the benefit in credits. The price is the same for all of this benefit's items. - name: displayName | type: string | description: Benefit name. - name: description | type: string | description: Benefit description. - name: itemInfo | type: ItemInfo | description: Display name for the catalog item. Only populated when ITEM is included in the fields request parameter. - name: displayName | type: string | description: Item display name. - name: benefitKey | type: string | description: Unique identifier for the benefit associated with this item. - name: itemSearchKey | type: string | description: Pre-computed search key for the item reference, built by concatenating provider_app_id, category, and external_id separated by /. Use this field for efficient single-field filtering instead of composing three separate conditions. - name: removed | type: boolean | description: Whether this item has been removed from the pool definition. - name: metadata | type: CursorPagingMetadata | description: Metadata for paginated results. - name: count | type: integer | description: Number of items returned in the response. - name: cursors | type: Cursors | description: Cursor strings that point to the next page, previous page, or both. - name: next | type: string | description: Cursor string pointing to the next page in the list of results. - name: prev | type: string | description: Cursor pointing to the previous page in the list of results. - name: hasNext | type: boolean | description: Whether there are more pages to retrieve following the current page. + `true`: Another page of results can be retrieved. + `false`: This is the last page. ``` ### Examples ### QueryPoolDefinitionItems ```curl ~~~cURL curl -X POST "https://www.wixapis.com/benefit-programs/v1/pool-definition-items/query" \ -H 'Content-type: application/json' \ -H 'Authorization: ' \ -d '{ "query": { "filter": { "$and": [ { "pool_definition_id": { "$eq": "201db180-5043-45cf-a501-bd9c06df5ae5" } }, { "benefit_key": { "$eq": "unlimited-classes" } } ] }, "sort": [ { "field_name": "created_date", "order": "ASC" } ], "cursor_paging": { "limit": 100 } } }' ~~~ ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.benefitPrograms.PoolDefinitionItemService.queryPoolDefinitionItems(query, options) Description: Retrieves a list of up to 1,000 pool definition items based on the specified paging, filtering, and sorting. To learn how to query pool definition items, see [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language). Pass 1 or more values in the `fields` parameter to populate additional data: - `POOL_DEFINITION`: Populates `poolDefinition` with the pool definition's display name, description, and credit configuration. - `PROGRAM_DEFINITION`: Populates `programDefinitions` with `displayName` and description. Use this field to show which plans grant access to a specified item. - `BENEFIT`: Populates `benefitInfo` with the benefit's credit price, display name, and description. - `ITEM`: Populates `itemInfo` with the catalog item's display name. Enrichment data is silently absent if the source data is unavailable. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: query Method parameters: param name: options | type: QueryPoolDefinitionItemsOptions none - name: fields | type: array | description: Fields to be included in the response. - enum: - POOL_DEFINITION: Populates the `poolDefinition` field with display name, description, and credit configuration. - PROGRAM_DEFINITION: Populates the `programDefinitions` field with `displayName` and description. - BENEFIT: Populates the `benefitInfo` field with credit price, name, and description. - ITEM: Populates the `itemInfo` field with the catalog item's display name. param name: query | type: PoolDefinitionItemQuery | required: true - name: cursorPaging | type: CursorPaging | description: Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not `filter` or `sort`. - name: limit | type: integer | description: Maximum number of items to return in the results. - name: cursor | type: string | description: Pointer to the next or previous page in the list of results. Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. - name: filter | type: object | description: Filter object in the following format: `"filter" : { "fieldName1": "value1", "fieldName2":{"$operator":"value2"} }` Example of operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, `$contains` - name: sort | type: array | description: Sort object in the following format: `[{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]` - name: fieldName | type: string | description: Name of the field to sort by. - name: order | type: SortOrder | description: Sort order. - enum: ASC, DESC Return type: PROMISE - name: poolDefinitionItems | type: array | description: List of items. - name: _id | type: string | description: Benefit item GUID. Deterministically generated from pool_definition_id and item_id — if you know both, you can compute the GUID without querying. - name: revision | type: string | description: Revision number, which increments by 1 each time the benefit item is updated. - name: _createdDate | type: Date | description: Date and time the item was created. - name: _updatedDate | type: Date | description: Date and time the item was updated. - name: externalId | type: string | description: External item GUID assigned by the provider of the items. For example, if the benefit items are products, this GUID corresponds to the specific product GUID in the provider's system. - name: category | type: string | description: Item category. Groups benefit items together for organization and management purposes. For example, classes, posts, groups. - name: providerAppId | type: string | description: GUID of the application providing the benefit items. Each item's external_id is unique within its provider application. - name: namespace | type: string | description: Namespace for your app or site's benefit programs. Namespaces allow you to distinguish between entities that you created and entities that other apps created. - name: poolDefinitionId | type: string | description: GUID of the pool definition - the configuration that defines a set of benefits and which items are accessible within each benefit. - name: itemSetId | type: string | description: Internal grouping identifier for this benefit's item set. Use pool_definition_id together with benefit_key to identify a benefit — item_set_id is an implementation detail. - name: poolDefinition | type: PoolDefinitionInfo | description: Pool definition details including display name, description, and credit settings. Only populated when POOL_DEFINITION is included in the fields request parameter. - name: displayName | type: string | description: Pool definition name. - name: description | type: string | description: Pool definition description. - name: creditConfiguration | type: CreditConfiguration | description: Credit configuration for this pool definition. When absent, benefits in this pool do not support credit-based pricing. - name: amount | type: string | description: Number of credits initially granted to a subscriber when this pool definition's benefits are activated. - name: unitDisplayName | type: string | description: Credit unit display name. - name: unitType | type: string | description: Credit unit type. - name: programDefinitions | type: array | description: Program definitions that include this item as an accessible benefit. Only id and external_id are returned by default; request PROGRAM_DEFINITION to include display_name and description. - name: _id | type: string | description: Program definition id - name: externalId | type: string | description: Program definition external id - name: displayName | type: string | description: Program definition name - name: description | type: string | description: Program definition description. - name: itemId | type: string | description: Item GUID. - name: benefitInfo | type: BenefitInfo | description: Pricing and display information for the associated benefit, including credit price, name, and description. Only populated when BENEFIT is included in the fields request parameter. - name: price | type: string | description: Price of the benefit in credits. The price is the same for all of this benefit's items. - name: displayName | type: string | description: Benefit name. - name: description | type: string | description: Benefit description. - name: itemInfo | type: ItemInfo | description: Display name for the catalog item. Only populated when ITEM is included in the fields request parameter. - name: displayName | type: string | description: Item display name. - name: benefitKey | type: string | description: Unique identifier for the benefit associated with this item. - name: itemSearchKey | type: string | description: Pre-computed search key for the item reference, built by concatenating provider_app_id, category, and external_id separated by /. Use this field for efficient single-field filtering instead of composing three separate conditions. - name: removed | type: boolean | description: Whether this item has been removed from the pool definition. - name: metadata | type: CursorPagingMetadata | description: Metadata for paginated results. - name: count | type: integer | description: Number of items returned in the response. - name: cursors | type: Cursors | description: Cursor strings that point to the next page, previous page, or both. - name: next | type: string | description: Cursor string pointing to the next page in the list of results. - name: prev | type: string | description: Cursor pointing to the previous page in the list of results. - name: hasNext | type: boolean | description: Whether there are more pages to retrieve following the current page. + `true`: Another page of results can be retrieved. + `false`: This is the last page. ``` ### Examples ### queryPoolDefinitionItems ```javascript import { poolDefinitionItems } from '@wix/benefit-programs'; async function queryPoolDefinitionItems(query,options) { const response = await poolDefinitionItems.queryPoolDefinitionItems(query,options); }; ``` ### queryPoolDefinitionItems (with elevated permissions) ```javascript import { poolDefinitionItems } from '@wix/benefit-programs'; import { auth } from '@wix/essentials'; async function myQueryPoolDefinitionItemsMethod(query,options) { const elevatedQueryPoolDefinitionItems = auth.elevate(poolDefinitionItems.queryPoolDefinitionItems); const response = await elevatedQueryPoolDefinitionItems(query,options); } ``` ### queryPoolDefinitionItems (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { poolDefinitionItems } from '@wix/benefit-programs'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { poolDefinitionItems }, // Include the auth strategy and host as relevant }); async function queryPoolDefinitionItems(query,options) { const response = await myWixClient.poolDefinitionItems.queryPoolDefinitionItems(query,options); }; ``` ---