> 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 # CheckBenefitEligibilityByFilter # Package: benefitPrograms # Namespace: PoolService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/pools/check-benefit-eligibility-by-filter.md ## Permission Scopes: Manage benefit programs: SCOPE.BENEFIT_PROGRAMS.MANAGE ## Introduction Checks benefit eligibility across the pools that match the filter. The filter selects pools (not individual benefits), using the same fields supported by Query Pools. For field support, see [Filtering and Sorting](https://dev.wix.com/docs/rest/business-solutions/benefit-programs/pools/filtering-and-sorting.md). To be redeemed, a benefit's pool must be active and the associated balance must be greater than the cost of the benefit. Each benefit is checked independently. For example, if there is a benefit with a price of 3 credits and a benefit with a price of 4 credits, and there are 5 available credits, both benefits would be returned as eligible, but they can't both be redeemed. --- ## REST API ### Schema ``` Method: checkBenefitEligibilityByFilter Description: Checks benefit eligibility across the pools that match the filter. The filter selects pools (not individual benefits), using the same fields supported by Query Pools. For field support, see [Filtering and Sorting](https://dev.wix.com/docs/rest/business-solutions/benefit-programs/pools/filtering-and-sorting.md). To be redeemed, a benefit's pool must be active and the associated balance must be greater than the cost of the benefit. Each benefit is checked independently. For example, if there is a benefit with a price of 3 credits and a benefit with a price of 4 credits, and there are 5 available credits, both benefits would be returned as eligible, but they can't both be redeemed. URL: https://www.wixapis.com/benefit-programs/v1/pools/check-benefit-eligibility-by-filter Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: namespace, count, itemReference, itemReference.externalId, itemReference.providerAppId Method parameters: param name: additionalData | type: additionalData | description: Additional information. param name: beneficiary | type: IdentificationData - ONE-OF: - name: anonymousVisitorId | type: string | description: GUID of a site visitor that hasn't logged in to the site. | validation: format GUID - name: memberId | type: string | description: GUID of a site member. | validation: format GUID - name: wixUserId | type: string | description: GUID of a Wix user. | validation: format GUID param name: count | type: count | description: Number of items to check. Ensures the balance is high enough to redeem this many items. | required: true | validation: minimum 1 param name: itemReference | type: ItemReference | required: true - name: externalId | type: string | description: External GUID of the item. | required: true | validation: format GUID - name: category | type: string | description: Item category. | validation: maxLength 20 - name: providerAppId | type: string | description: GUID of the app providing the item. | required: true | validation: format GUID param name: namespace | type: namespace | 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. | required: true | validation: minLength 1, maxLength 20 param name: poolFilter | type: PoolFilter - name: filter | type: object | description: Filter object. See [API Query Language](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md) for more information. For supported filterable and sortable fields, see [Filtering and Sorting](https://dev.wix.com/docs/rest/business-solutions/benefit-programs/pools/filtering-and-sorting.md). - name: sort | type: array | description: Sorting to apply to the matched pools. Determines the order of the returned results, and which results are kept when more than 100 are produced. | validation: maxItems 5 - name: fieldName | type: string | description: Field to sort by. | validation: maxLength 512 - name: order | type: SortOrder | description: Sort order. Use `ASC` for ascending order or `DESC` for descending order. Default: `ASC` - enum: - ASC: Ascending sort order. - DESC: Descending sort order. param name: targetDate | type: targetDate | description: Date that the item will be provided to the beneficiary. This parameter should be used to manage the potential logistics of providing the item. | validation: format date-time Return type: CheckBenefitEligibilityByFilterResponse - name: results | type: array | description: Results of the eligibility check for the benefits in the pools that matched the filter. A pool that contains multiple benefits for the requested item produces one result per benefit. Empty when no pools match the filter. Capped at 100 results. When more than 100 results are produced, only the first 100, in the order specified by `poolFilter.sort`, are returned. | validation: maxItems 100 - name: benefitResults | type: array | description: Eligibility status. | validation: maxItems 10 - ONE-OF: - name: eligibleBenefitOptions | type: EligibleBenefit | description: Returned when item is eligible to be redeemed. - name: poolId | type: string | description: Pool GUID. | validation: format GUID - name: benefitKey | type: string | description: Benefit key. | validation: maxLength 64 - name: itemReference | type: ItemReference | description: Item reference. - name: externalId | type: string | description: External GUID of the item. | validation: format GUID - name: category | type: string | description: Item category. | validation: maxLength 20 - name: providerAppId | type: string | description: GUID of the app providing the item. | validation: format GUID - name: price | type: string | description: Price of the benefit in credits. | validation: decimalValue {"gte":"0","maxScale":4} - name: notEnoughBalanceOptions | type: NotEnoughBalance | description: Returned when the pool's associated balance is lower than the cost of redeeming the items. - name: poolId | type: string | description: Pool GUID. | validation: format GUID - name: itemReference | type: ItemReference | description: Item reference. - name: availableBalance | type: string | description: Pool's associated balance amount in credits. | validation: decimalValue {"maxScale":4} - name: requestedBalance | type: string | description: Price of the item in credits. | validation: decimalValue {"maxScale":4} - name: policyExpressionEvaluatedToFalseOptions | type: PolicyExpressionEvaluatedToFalse | description: Returned when the policy is false. - name: poolId | type: string | description: Pool GUID. | validation: format GUID - name: itemReference | type: ItemReference | description: Item reference. - name: failureDetails | type: array | description: Failure details. | validation: maxItems 10 - name: code | type: string | description: Failure code | validation: minLength 1, maxLength 64 - name: message | type: string | description: Failure message | validation: maxLength 256 - name: policyId | type: string | description: Policy id | validation: format GUID - name: appId | type: string | description: App that owns the policy | validation: format GUID - name: errorData | type: object | description: Information provided by the policy - name: poolNotActiveOptions | type: PoolNotActive | description: Returned when the pool isn't active. - name: poolId | type: string | description: Pool GUID. | validation: format GUID - name: poolStatus | type: PoolStatus | description: Pool status. - enum: - ACTIVE: Pool is active. - PAUSED: Pool is paused. It can be resumed. - ENDED: Pool is ended. It can't be resumed. - PROVISIONING: Pool provisioning is in progress. This status exists for a short time during processing. - RENEWING: Pool renewing is in progress. This status exists for a short time during processing. - PENDING: Pool is pending - name: benefitNotFoundOptions | type: BenefitNotFound | description: Returned when invalid benefit details are provided. - name: poolId | type: string | description: Pool GUID. | validation: format GUID - name: benefitKey | type: string | description: Specified benefit key. | validation: maxLength 64 - name: poolNotFoundOptions | type: PoolNotFound | description: Returned when invalid pool details are provided. - name: poolId | type: string | description: Pool GUID. | validation: format GUID - name: type | type: Type | description: Eligibility status. - enum: - ELIGIBLE_BENEFIT: Item is eligible to be redeemed. - NOT_ENOUGH_BALANCE: Balance is lower than the cost of redeeming the items. - POOL_NOT_ACTIVE: Pool isn't active. - BENEFIT_NOT_FOUND: Invalid benefit details provided. - POOL_NOT_FOUND: Invalid pool details provided. Possible Errors: HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: INVALID_ITEM_REFERENCE | Description: The `itemReference` contains invalid values. ``` ### Examples ### CheckBenefitEligibilityByFilter ```curl ~~~cURL curl --request POST https://www.wixapis.com/benefit-programs/v1/pools/check-benefit-eligibility-by-filter \ -H "Authorization: " \ -H "Content-Type: application/json" \ --data '{ "pool_filter": { "filter": { "$and": [ { "programId": { "$eq": "8faed6d2-dfdf-44f1-8a71-bcc19d2fbdde" } }, { "status": { "$eq": "ACTIVE" } } ] }, "sort": [ { "fieldName": "createdDate", "order": "DESC" } ] }, "item_reference": { "external_id": "57273802-b873-495c-8eba-b8f054452e6c", "provider_app_id": "00000000-0000-0000-0000-000000000000" }, "count": 3, "beneficiary": { "identity_type": "MEMBER", "member_id": "00000000-0000-0000-0000-000000000000" }, "namespace": "benefit_programs_app" }' ~~~ ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.benefitPrograms.pools.checkBenefitEligibilityByFilter(options) Description: Checks benefit eligibility across the pools that match the filter. The filter selects pools (not individual benefits), using the same fields supported by Query Pools. For field support, see [Filtering and Sorting](https://dev.wix.com/docs/rest/business-solutions/benefit-programs/pools/filtering-and-sorting.md). To be redeemed, a benefit's pool must be active and the associated balance must be greater than the cost of the benefit. Each benefit is checked independently. For example, if there is a benefit with a price of 3 credits and a benefit with a price of 4 credits, and there are 5 available credits, both benefits would be returned as eligible, but they can't both be redeemed. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: options.namespace, options.count, options.itemReference, options.itemReference.externalId, options.itemReference.providerAppId, options Method parameters: param name: options | type: CheckBenefitEligibilityByFilterOptions none | required: true - name: poolFilter | type: PoolFilter | description: Defines filtering and sorting criteria used to select pools when checking eligibility. The filter selects pools using the same fields supported by Query Pools. For field support, see [Filtering and Sorting](https://dev.wix.com/docs/rest/business-solutions/benefit-programs/pools/filtering-and-sorting.md). When omitted, eligibility is checked across all pools in the namespace that match the provided `beneficiary`. Combined with `beneficiary` and `namespace`, the filter further narrows which pools are checked. - name: filter | type: object | description: Filter object. See [API Query Language](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md) for more information. For supported filterable and sortable fields, see [Filtering and Sorting](https://dev.wix.com/docs/rest/business-solutions/benefit-programs/pools/filtering-and-sorting.md). - name: sort | type: array | description: Sorting to apply to the matched pools. Determines the order of the returned results, and which results are kept when more than 100 are produced. | validation: maxItems 5 - name: fieldName | type: string | description: Field to sort by. | validation: maxLength 512 - name: order | type: SortOrder | description: Sort order. Use `ASC` for ascending order or `DESC` for descending order. Default: `ASC` - enum: - ASC: Ascending sort order. - DESC: Descending sort order. - 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. | required: true | validation: minLength 1, maxLength 20 - name: itemReference | type: ItemReference | description: Information about the item to check. | required: true - name: externalId | type: string | description: External GUID of the item. | required: true | validation: format GUID - name: category | type: string | description: Item category. | validation: maxLength 20 - name: providerAppId | type: string | description: GUID of the app providing the item. | required: true | validation: format GUID - name: count | type: integer | description: Number of items to check. Ensures the balance is high enough to redeem this many items. | required: true | validation: minimum 1 - name: targetDate | type: Date | description: Date that the item will be provided to the beneficiary. This parameter should be used to manage the potential logistics of providing the item. - name: beneficiary | type: IdentificationData | description: Pool beneficiary. When provided, only the beneficiary's pools that also match `pool_filter` are checked. - ONE-OF: - name: anonymousVisitorId | type: string | description: GUID of a site visitor that hasn't logged in to the site. | validation: format GUID - name: memberId | type: string | description: GUID of a site member. | validation: format GUID - name: wixUserId | type: string | description: GUID of a Wix user. | validation: format GUID - name: additionalData | type: object | description: Additional information. Return type: PROMISE - name: results | type: array | description: Results of the eligibility check for the benefits in the pools that matched the filter. A pool that contains multiple benefits for the requested item produces one result per benefit. Empty when no pools match the filter. Capped at 100 results. When more than 100 results are produced, only the first 100, in the order specified by `poolFilter.sort`, are returned. | validation: maxItems 100 - name: benefitResults | type: array | description: Eligibility status. | validation: maxItems 10 - ONE-OF: - name: eligibleBenefitOptions | type: EligibleBenefit | description: Returned when item is eligible to be redeemed. - name: poolId | type: string | description: Pool GUID. | validation: format GUID - name: benefitKey | type: string | description: Benefit key. | validation: maxLength 64 - name: itemReference | type: ItemReference | description: Item reference. - name: externalId | type: string | description: External GUID of the item. | validation: format GUID - name: category | type: string | description: Item category. | validation: maxLength 20 - name: providerAppId | type: string | description: GUID of the app providing the item. | validation: format GUID - name: price | type: string | description: Price of the benefit in credits. | validation: decimalValue {"gte":"0","maxScale":4} - name: notEnoughBalanceOptions | type: NotEnoughBalance | description: Returned when the pool's associated balance is lower than the cost of redeeming the items. - name: poolId | type: string | description: Pool GUID. | validation: format GUID - name: itemReference | type: ItemReference | description: Item reference. - name: availableBalance | type: string | description: Pool's associated balance amount in credits. | validation: decimalValue {"maxScale":4} - name: requestedBalance | type: string | description: Price of the item in credits. | validation: decimalValue {"maxScale":4} - name: policyExpressionEvaluatedToFalseOptions | type: PolicyExpressionEvaluatedToFalse | description: Returned when the policy is false. - name: poolId | type: string | description: Pool GUID. | validation: format GUID - name: itemReference | type: ItemReference | description: Item reference. - name: failureDetails | type: array | description: Failure details. | validation: maxItems 10 - name: code | type: string | description: Failure code | validation: minLength 1, maxLength 64 - name: message | type: string | description: Failure message | validation: maxLength 256 - name: policyId | type: string | description: Policy id | validation: format GUID - name: appId | type: string | description: App that owns the policy | validation: format GUID - name: errorData | type: object | description: Information provided by the policy - name: poolNotActiveOptions | type: PoolNotActive | description: Returned when the pool isn't active. - name: poolId | type: string | description: Pool GUID. | validation: format GUID - name: poolStatus | type: PoolStatus | description: Pool status. - enum: - ACTIVE: Pool is active. - PAUSED: Pool is paused. It can be resumed. - ENDED: Pool is ended. It can't be resumed. - PROVISIONING: Pool provisioning is in progress. This status exists for a short time during processing. - RENEWING: Pool renewing is in progress. This status exists for a short time during processing. - PENDING: Pool is pending - name: benefitNotFoundOptions | type: BenefitNotFound | description: Returned when invalid benefit details are provided. - name: poolId | type: string | description: Pool GUID. | validation: format GUID - name: benefitKey | type: string | description: Specified benefit key. | validation: maxLength 64 - name: poolNotFoundOptions | type: PoolNotFound | description: Returned when invalid pool details are provided. - name: poolId | type: string | description: Pool GUID. | validation: format GUID - name: type | type: Type | description: Eligibility status. - enum: - ELIGIBLE_BENEFIT: Item is eligible to be redeemed. - NOT_ENOUGH_BALANCE: Balance is lower than the cost of redeeming the items. - POOL_NOT_ACTIVE: Pool isn't active. - BENEFIT_NOT_FOUND: Invalid benefit details provided. - POOL_NOT_FOUND: Invalid pool details provided. Possible Errors: HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: INVALID_ITEM_REFERENCE | Description: The `itemReference` contains invalid values. ``` ### Examples ### checkBenefitEligibilityByFilter ```javascript import { pools } from '@wix/benefit-programs'; async function checkBenefitEligibilityByFilter(options) { const response = await pools.checkBenefitEligibilityByFilter(options); }; ``` ### checkBenefitEligibilityByFilter (with elevated permissions) ```javascript import { pools } from '@wix/benefit-programs'; import { auth } from '@wix/essentials'; async function myCheckBenefitEligibilityByFilterMethod(options) { const elevatedCheckBenefitEligibilityByFilter = auth.elevate(pools.checkBenefitEligibilityByFilter); const response = await elevatedCheckBenefitEligibilityByFilter(options); } ``` ### checkBenefitEligibilityByFilter (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 { pools } from '@wix/benefit-programs'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { pools }, // Include the auth strategy and host as relevant }); async function checkBenefitEligibilityByFilter(options) { const response = await myWixClient.pools.checkBenefitEligibilityByFilter(options); }; ``` ---