> 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 # ListPlansByItemIdentifier # Package: pricingPlans # Namespace: PlanBenefitService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plan-benefits/list-plans-by-item-identifier.md ## Permission Scopes: Read Pricing Plans: SCOPE.DC-PAIDPLANS.READ-PLANS ## Introduction Returns plans associated with the provided item identifier that are available for purchase. The item is matched on all three `itemIdentifier` fields exactly, combined with AND. An omitted field matches the empty value rather than matching all values. Each returned plan contains only the pricing variants available for purchase. A variant is excluded when the target date is in the past, falls outside the plan's duration, falls outside the plan's start date limits, or when the plan's purchase limits are already reached for the member. Plans with no remaining variant are excluded from the response, as are benefits whose credit price cannot cover `count` items. A plan appears once per matching benefit, so the same plan may be returned more than once with different `benefitInfo`. Only plans that are public and not archived are considered. --- ## REST API ### Schema ``` Method: listPlansByItemIdentifier Description: Returns plans associated with the provided item identifier that are available for purchase. The item is matched on all three `itemIdentifier` fields exactly, combined with AND. An omitted field matches the empty value rather than matching all values. Each returned plan contains only the pricing variants available for purchase. A variant is excluded when the target date is in the past, falls outside the plan's duration, falls outside the plan's start date limits, or when the plan's purchase limits are already reached for the member. Plans with no remaining variant are excluded from the response, as are benefits whose credit price cannot cover `count` items. A plan appears once per matching benefit, so the same plan may be returned more than once with different `benefitInfo`. Only plans that are public and not archived are considered. URL: https://www.wixapis.com/pricing-plan-benefits/v3/plan-benefits/list-plans-by-item-identifier Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: itemIdentifier, itemIdentifier.externalId, itemIdentifier.providerAppId Method parameters: param name: count | type: count | description: Amount of items to check. Ensures the balance is high enough to redeem this many items: a plan is excluded when `count` multiplied by the benefit's credit price exceeds the credits the plan grants. Benefits with no credit configuration are never excluded by this check. Must be at least 1. Omitting the field is rejected. | validation: minimum 1 param name: itemIdentifier | type: ItemIdentifier | required: true - name: externalId | type: string | description: GUID of the item in the provider app's own system. | required: true | validation: format GUID - name: category | type: string | description: Category of the item, as defined by the provider app. Matched exactly. Omit only for items stored without a category. An omitted value matches only benefits with no category, it doesn't match all categories. | validation: maxLength 20 - name: providerAppId | type: string | description: GUID of the app providing the item. | required: true | validation: format GUID param name: targetDate | type: targetDate | description: Date that the item will be used. Plan duration and start date validations are calculated based on this date. If not provided, the current date is used. Resolved to a calendar day in the site's time zone, or in UTC when the site has no time zone. | validation: format date-time Return type: ListPlansByItemIdentifierResponse - name: planBenefits | type: array | description: Plans with associated benefit details. Each plan contains only pricing variants available for purchase. A plan appears once per matching benefit, so the same plan may be present more than once with different `benefitInfo`. | validation: maxItems 100 - name: planInfo | type: PlanInfo | description: Pricing plan that includes the benefit. - name: plan | type: Plan | description: Pricing plan, containing only the variants available for purchase. Prices reflect any pricing overrides active for the current context, so they may differ from the same plan returned by the Pricing Plans API. - name: id | type: string | description: Plan GUID. | read-only: true | validation: format GUID - name: revision | type: string | description: Revision number, which increments by 1 each time the plan is updated. | read-only: true | validation: format int64 - name: createdDate | type: string | description: Date and time the plan was created. | read-only: true | validation: format date-time - name: updatedDate | type: string | description: Date and time the plan was last updated. | read-only: true | validation: format date-time - name: name | type: string | description: Plan name displayed to customers. | validation: minLength 1, maxLength 50 - name: description | type: string | description: Plan description that explains what customers get with this plan. | validation: maxLength 450 - name: image | type: Image | description: Plan image displayed during checkout and on the site's **Plans & Pricing** page. - name: id | type: string | description: WixMedia image GUID. | validation: maxLength 255 - name: height | type: integer | description: Original image height. | read-only: true - name: width | type: integer | description: Original image width. | read-only: true - name: altText | type: string | description: Image alt text. | validation: maxLength 1000 - name: slug | type: string | description: Unique identifier for this plan within the Wix site. If not provided, generated automatically from the plan name. | validation: maxLength 255, format URL_SLUG - name: termsAndConditions | type: string | description: Terms and conditions text that customers must agree to when purchasing this plan. | validation: maxLength 3000 - name: pricingVariants | type: array | description: Pricing variants that define different billing and pricing options for this plan. Currently limited to 1 variant per plan. | validation: minItems 1, maxItems 20 - name: id | type: string | description: Pricing variant GUID. | validation: format GUID - name: name | type: string | description: Name for this pricing variant, such as "Monthly" or "Yearly". | validation: minLength 1, maxLength 255 - name: freeTrialDays | type: integer | description: Number of days customers can use the plan for free before the first charge. Set to `0` for no free trial. | validation: minimum 0, maximum 999 - name: fees | type: array | description: Additional fees applied to this pricing variant. | validation: maxItems 5 - ONE-OF: - name: fixedAmountOptions | type: FixedAmountOption | description: Fixed monetary amount for the fee. - name: amount | type: string | description: Fixed monetary amount. | validation: decimalValue {"gt":"0","maxScale":4} - name: id | type: string | description: | validation: format GUID - name: priceType | type: PriceType | description: Pricing type used for this fee. - enum: - FIXED_AMOUNT: Fee is charged as a fixed monetary amount. - name: name | type: string | description: Fee name displayed to customers, such as "Setup Fee" or "Processing Fee". | validation: minLength 1, maxLength 40 - name: appliedAt | type: AppliedAt | description: When this fee is charged during the customer's plan lifecycle. - enum: - FIRST_PAYMENT: Fee is added to the first payment. - name: billingTerms | type: BillingTerms | description: Billing configuration that defines when and how often customers are charged. - ONE-OF: - name: cyclesCompletedDetails | type: CyclesCompletedDetails | description: How many billing cycles the plan lasts. - name: billingCycleCount | type: string | description: Number of billing cycles before the plan automatically ends. For example, if `billingCycle` is 3 months and `billingCycleCount` is 4, the customer will be charged 4 times over 12 months before the plan expires. Only applicable if `endType` is `CYCLES_COMPLETED`. | validation: minimum 1, maximum 2000 - name: billingCycle | type: Duration | description: Duration of each billing cycle, such as 1 month or 2 weeks. Can't be less than 7 days. Only applicable for recurring plans. - name: period | type: Period | description: Duration of period. - enum: DAY, WEEK, MONTH, YEAR - name: count | type: string | description: Number of periods. | validation: minimum 1 - name: startType | type: StartType | description: When the billing starts. - enum: - ON_PURCHASE: Billing starts immediately after purchase. - CUSTOM: Customer can choose when billing starts. - name: endType | type: EndType | description: How long the plan remains active. Plans can run until canceled or for a specific number of billing cycles. Plan duration can't exceed 10 years. - enum: - UNTIL_CANCELLED: Plan continues until customer cancels. - CYCLES_COMPLETED: Plan ends after a specified number of billing cycles. - name: promotion | type: string | description: Promotional message displayed with this pricing variant. | validation: maxLength 255 - name: pricingStrategies | type: array | description: Pricing strategies that determine how much customers pay. Currently limited to 1 strategy per variant. | validation: minItems 1, maxItems 1 - ONE-OF: - name: flatRate | type: FlatRate | description: Single fixed cost charged regardless of usage. - name: amount | type: string | description: Fixed monetary amount. | validation: decimalValue {"gte":"0","maxScale":4} - name: visible | type: boolean | description: Whether this pricing variant is visible to customers. Defaults to `true` when not set. At least one variant per plan must remain visible. Variant-level visibility is independent from plan-level visibility (`Plan.visibility`). - name: categoryIds | type: array | description: IDs of the categories this variant belongs to. Categories group variants across plans (for example into a "Monthly / Yearly" selector) independently of billing cycle. Optional. | validation: maxItems 1, format GUID - name: priceOverrides | type: PriceOverrides | description: Rules that override this pricing variant's price for purchases that meet their conditions. Applied during purchase. An override that matches the purchase always replaces the variant's original price, even when the resulting price is higher. If multiple overrides match the same purchase, the lowest resulting price among them wins - the original price doesn't participate in this comparison. The overridden price applies to every billing cycle of the resulting subscription, not only the first payment. Updates replace the entire list of overrides. To remove all overrides, set this field to `null` - an empty overrides list isn't accepted. - name: overrides | type: array | description: Price override rules. | validation: minItems 1, maxItems 10 - ONE-OF: - name: fixedPriceOptions | type: FixedPriceOptions | description: Options for the `FIXED_PRICE` override type. - name: amount | type: string | description: Price that replaces the pricing variant's original price. Can be higher than the original price. | validation: decimalValue {"gte":"0","maxScale":4} - name: percentageDiscountOptions | type: PercentageDiscountOptions | description: Options for the `PERCENTAGE_DISCOUNT` override type. - name: percentage | type: string | description: Percentage to deduct from the pricing variant's original price. For example, `12.5` for a 12.5% discount. The discounted price is rounded to the number of decimal places supported by the plan's currency. | validation: decimalValue {"gt":"0","lte":"100","maxScale":2} - name: id | type: string | description: Price override GUID. Must be unique within the pricing variant. | validation: format GUID - name: conditions | type: PurchaseConditions | description: Conditions a purchase must meet for this override to apply. - ONE-OF: - name: specificMembersOptions | type: SpecificMembersOptions | description: Options for the `SPECIFIC_MEMBERS` customer eligibility. - name: memberIds | type: array | description: IDs of the members the override applies to. The logged-in buyer must be one of these members. | validation: minItems 1, maxItems 50, format GUID - name: customerEligibility | type: CustomerEligibility | description: Which customers the override applies to. - enum: - ALL: The override applies to all customers. - RETURNING: The override applies only to returning customers - members with at least 1 plan subscription on the site, counted across all plans by the member's contact. Pending, active, paused, ended, and canceled subscriptions count; draft subscriptions don't. - SPECIFIC_MEMBERS: The override applies only to the specified members. - name: validFromDate | type: string | description: Date and time from which the override applies. The purchase must happen on or after this exact instant. When `valid_until_date` is also set, must be earlier than `valid_until_date` - equal values are rejected. | validation: format date-time - name: validUntilDate | type: string | description: Date and time until which the override applies. The purchase must happen before this exact instant. | validation: format date-time - name: overrideType | type: OverrideType | description: How the pricing variant's price is overridden. - enum: - FIXED_PRICE: The pricing variant's price is replaced with a fixed price. - PERCENTAGE_DISCOUNT: The pricing variant's price is reduced by a percentage. - name: feeOverrides | type: FeeOverrides | description: Rules that override specific fees of this pricing variant for purchases that meet their conditions. Applied during purchase. If multiple overrides apply to the same fee, the lowest resulting fee amount wins, with a waived fee counting as `0`. Updates replace the entire list of overrides. To remove all overrides, set this field to `null` - an empty overrides list isn't accepted. - name: overrides | type: array | description: Fee override rules. | validation: minItems 1, maxItems 10 - ONE-OF: - name: fixedAmountOptions | type: FixedAmountOptions | description: Options for the `FIXED_AMOUNT` override type. - name: amount | type: string | description: Amount that replaces the fee's original amount. Must be greater than `0`. To remove the fee from the purchase, use the `WAIVED` override type instead. | validation: decimalValue {"gt":"0","maxScale":4} - name: id | type: string | description: Fee override GUID. Must be unique within the pricing variant. | validation: format GUID - name: feeId | type: string | description: GUID of the fee on the same pricing variant that this override applies to. | validation: format GUID - name: conditions | type: PurchaseConditions | description: Conditions a purchase must meet for this override to apply. - name: overrideType | type: OverrideType | description: How the fee is overridden. - enum: - FIXED_AMOUNT: The fee's amount is replaced with a fixed amount. - WAIVED: The fee isn't applied to the purchase at all. - name: perks | type: array | description: List of text snippets describing what the plan offers. For display purposes only. | validation: maxItems 500 - name: id | type: string | description: Perk GUID. | validation: format GUID - name: description | type: string | description: Perk description. | validation: minLength 1, maxLength 1400 - name: visibility | type: Visibility | description: Plan visibility. - enum: - PUBLIC: Plan is visible and available for purchase by all customers. - PRIVATE: Plan isn't visible to new customers unless they get a specific link to the plan. Existing buyers can continue using it. - name: buyable | type: boolean | description: Whether customers can currently purchase this plan. If set to `false`, customer won't be able to buy a plan themselves. In this case a Wix user has to assign the plan through the [dashboard](https://support.wix.com/en/article/pricing-plans-selling-plans-offline). - name: formId | type: string | description: GUID of the form associated with the plan at checkout. | validation: format GUID - name: buyerCanCancel | type: boolean | description: Whether buyers can cancel their subscription to this plan. - name: currency | type: string | description: Three-letter currency code in [ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. When the site currency changes, monetary amounts stored on the plan (prices, fees, and override amounts) are automatically rounded to the number of decimal places supported by the new currency. | read-only: true | validation: format CURRENCY - name: purchaseLimits | type: array | description: Caps how many subscriptions buyers can have or the site can sell for this plan. When multiple types are present, all must pass (AND logic). Duplicate types are rejected by the server. | validation: maxItems 4 - name: type | type: PurchaseLimitType | description: The type of purchase limit. - enum: - PER_MEMBER_LIFETIME: Limits the total number of subscriptions (any status) a single member can have over their lifetime. - PER_MEMBER_ACTIVE: Limits the number of ongoing (ACTIVE, PENDING, PAUSED) subscriptions a single member can have at any time. - TOTAL_ACTIVE: Limits the total number of ongoing (ACTIVE, PENDING, PAUSED) subscriptions across all members at any time. - TOTAL_SOLD: Limits the total number of subscriptions ever created (any status) across all members. - name: maxCount | type: integer | description: The maximum number of subscriptions allowed. | validation: minimum 1, maximum 10000 - name: benefitDistributionSettings | type: BenefitDistributionSettings | description: The settings of the benefit distribution for subscriptions to this plan - ONE-OF: - name: customScheduleOptions | type: CustomScheduleOptions | description: Custom schedule - name: cycleDuration | type: Duration | description: Cycle duration - name: unit | type: DurationUnit | description: Duration unit: DAY, WEEK, MONTH, YEAR - enum: UNKNOWN, DAY, WEEK, MONTH, YEAR - name: count | type: integer | description: Amount of units. For example, 1 MONTH, 1 YEAR, 2 WEEKS, etc. Optional. Default is 1. | validation: minimum 1, format int32 - name: distributionStrategyType | type: DistributionStrategyType | description: The distribution strategy of the benefits for this subscription, which is used to determine how the benefits are distributed in each cycle. - enum: UNKNOWN_DISTRIBUTION_STRATEGY_TYPE, PER_BILLING_CYCLE, CUSTOM_SCHEDULE - name: startDateSettings | type: StartDateSettings | description: Settings that control when subscriptions to this plan start. Applied during purchase to calculate the subscription start date and validate customer-selected start dates. The settings apply only to pricing variants with a compatible `billing_terms.start_type`: `FIXED_DATE` and `DAY_OF_MONTH` apply to variants with the `ON_PURCHASE` start type, while `DATE_RANGE` applies to variants with the `CUSTOM` start type. - ONE-OF: - name: fixedDateOptions | type: FixedDateOptions | description: Subscription starts on the earliest of the configured fixed dates that hasn't passed. - name: startDates | type: array | description: Dates on which a subscription can start. A purchase starts the subscription on the earliest listed date that hasn't passed in the site's time zone. A purchase made on one of the dates starts the subscription immediately. When every date has passed the plan can't be purchased and `start_date_unavailable_message` is displayed. Only the calendar date in the site's time zone is used, the time of day is ignored. Order doesn't matter. Dates must be unique. | validation: maxItems 5 - name: dayOfMonthOptions | type: DayOfMonthOptions | description: Subscription starts on a specific day of each month. - name: dayOfMonth | type: integer | description: Day of the month the subscription starts. For months with fewer days, the subscription starts on the last day of the month. If the purchase happens on the configured day, the subscription starts on that same day. Only determines the subscription start date - subsequent billing cycles follow the pricing variant's `billing_terms.billing_cycle` from that start date. | validation: minimum 1, maximum 31 - name: dateRangeOptions | type: DateRangeOptions | description: Customer selects a start date within a date range. - name: startDate | type: string | description: Date and time from which the customer can select the subscription start date. The selected start date must be on or after this exact instant. | validation: format date-time - name: endDate | type: string | description: Date and time until which the customer can select the subscription start date. If not set, the range is open-ended. The selected start date must be before this exact instant. Must be later than `start_date`. | validation: format date-time - name: type | type: StartDateType | description: How the subscription start date is determined. - enum: - FIXED_DATE: Subscription starts on the earliest of the configured fixed dates that hasn't passed. Applies only to pricing variants with the `ON_PURCHASE` start type. - DAY_OF_MONTH: Subscription starts on a specific day of each month. Applies only to pricing variants with the `ON_PURCHASE` start type. - DATE_RANGE: Customer selects a start date within a date range. Applies only to pricing variants with the `CUSTOM` start type. - name: startDateUnavailableMessage | type: string | description: Message displayed to customers when no start date is available. For example, when every fixed start date or the end of the date range has passed. Applicable only when `type` is `FIXED_DATE`, or `DATE_RANGE` with `date_range_options.end_date` set - in other configurations a start date is always available and the message is ignored. | validation: minLength 1, maxLength 512 - name: tags | type: Tags | description: Tags that can be assigned to this plan for classification and filtering. - name: privateTags | type: TagList | description: Tags that require an additional permission in order to access them, normally not given to site members or visitors. - name: tagIds | type: array | description: List of tag GUIDs | validation: maxItems 100, maxLength 5 - name: publicTags | type: TagList | description: Tags that are exposed to anyone who has access to the labeled entity itself, including site members and visitors. - name: extendedFields | type: ExtendedFields | description: Data extensions. Learn more about [extended fields](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md). - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). | validation: format map - name: nextStartDate | type: string | description: Date the plan becomes active when purchased now. Returned only when at least one available variant has `ON_PURCHASE` start type and a start date rule is configured. Absent in two cases: the plan starts immediately on purchase, or the buyer chooses the start date. Check the variant's `billing_terms.start_type` to tell which. | validation: format date-time - name: benefitInfo | type: BenefitInfo | description: Benefit that grants access to the item. - name: externalId | type: string | description: GUID of the item in the provider app's own system. For example, if the benefit items are products, this GUID corresponds to the specific product GUID in the provider's system. | read-only: true | validation: format GUID, immutable - name: category | type: string | description: Item category. Groups benefit items together for organization and management purposes. For example, classes, posts, groups. Always the same value passed in `item_identifier.category`. Categories are defined by the provider app, not by Wix. An empty string means the item has no category. | read-only: true | validation: maxLength 20, immutable - name: providerAppId | type: string | description: GUID of the application providing the benefit item. GUID of the external application supplying the items. Each item's external GUID is unique to its respective provider's application. | read-only: true | validation: format GUID, immutable - name: poolDefinitionId | type: string | description: GUID of the Benefit Programs pool definition that this benefit belongs to. Use together with `benefit_key` to identify a benefit. | read-only: true | validation: format GUID, immutable - name: itemSetId | type: string | description: Link between the benefit outlined in a pool definition and the specific item included in that benefit. Defined by the Benefit Programs API. To identify a benefit, use `pool_definition_id` together with `benefit_key`. | read-only: true | validation: format GUID, immutable - name: price | type: string | description: Price of the benefit, expressed in the credit unit given by `credit_configuration.unit_type`. The price is the same for all of this benefit's items. Not a currency amount. | validation: decimalValue {"gte":"0","maxScale":4} - name: creditConfiguration | type: CreditConfiguration | description: Credit settings of the pool that this benefit belongs to. When absent, benefits do not support credit-based pricing. - name: amount | type: string | description: Number of credits granted when the plan is purchased, expressed in `unit_type`. This is the starting balance and doesn't reflect credits already used. | validation: decimalValue {"gte":"0","maxScale":4} - name: unitDisplayName | type: string | description: Name of the credit unit to display to buyers. For example, `Sessions`. | validation: maxLength 32 - name: unitType | type: string | description: Machine-readable credit unit type. For example, `PUNCH_CARD`. Defined by the provider app rather than by a fixed Wix set, so treat it as opaque. Use `unit_display_name` for anything shown to buyers. | validation: maxLength 16 - name: benefitKey | type: string | description: Identifier of the benefit, unique within its pool definition. Stable across requests, so it's safe to store and compare. The format is defined by the provider app, so treat it as opaque. | validation: maxLength 64 - name: displayName | type: string | description: Benefit name. | validation: maxLength 40 - name: description | type: string | description: Benefit description. | validation: maxLength 255 ``` ### Examples ### List Plans by Item Identifier Retrieves the pricing plans a customer can purchase in order to use a specific item, such as a class or a session, together with the benefit that grants access to it. ```curl curl -X POST \ 'https://www.wixapis.com/pricing-plan-benefits/v3/plan-benefits/list-plans-by-item-identifier' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -d '{ "itemIdentifier": { "externalId": "c0b0bd57-ff8e-4525-a577-04796b22cd60", "providerAppId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97" }, "targetDate": "2026-10-06T09:00:00.000Z", "count": 1 }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.pricingPlans.planBenefits.listPlansByItemIdentifier(itemIdentifier, options) Description: Returns plans associated with the provided item identifier that are available for purchase. The item is matched on all three `itemIdentifier` fields exactly, combined with AND. An omitted field matches the empty value rather than matching all values. Each returned plan contains only the pricing variants available for purchase. A variant is excluded when the target date is in the past, falls outside the plan's duration, falls outside the plan's start date limits, or when the plan's purchase limits are already reached for the member. Plans with no remaining variant are excluded from the response, as are benefits whose credit price cannot cover `count` items. A plan appears once per matching benefit, so the same plan may be returned more than once with different `benefitInfo`. Only plans that are public and not archived are considered. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: itemIdentifier, itemIdentifier.externalId, itemIdentifier.providerAppId Method parameters: param name: itemIdentifier | type: ItemIdentifier | required: true - name: externalId | type: string | description: GUID of the item in the provider app's own system. | required: true | validation: format GUID - name: category | type: string | description: Category of the item, as defined by the provider app. Matched exactly. Omit only for items stored without a category. An omitted value matches only benefits with no category, it doesn't match all categories. | validation: maxLength 20 - name: providerAppId | type: string | description: GUID of the app providing the item. | required: true | validation: format GUID param name: options | type: ListPlansByItemIdentifierOptions none - name: targetDate | type: Date | description: Date that the item will be used. Plan duration and start date validations are calculated based on this date. If not provided, the current date is used. Resolved to a calendar day in the site's time zone, or in UTC when the site has no time zone. - name: count | type: integer | description: Amount of items to check. Ensures the balance is high enough to redeem this many items: a plan is excluded when `count` multiplied by the benefit's credit price exceeds the credits the plan grants. Benefits with no credit configuration are never excluded by this check. Must be at least 1. Omitting the field is rejected. | validation: minimum 1 Return type: PROMISE - name: planBenefits | type: array | description: Plans with associated benefit details. Each plan contains only pricing variants available for purchase. A plan appears once per matching benefit, so the same plan may be present more than once with different `benefitInfo`. | validation: maxItems 100 - name: planInfo | type: PlanInfo | description: Pricing plan that includes the benefit. - name: plan | type: Plan | description: Pricing plan, containing only the variants available for purchase. Prices reflect any pricing overrides active for the current context, so they may differ from the same plan returned by the Pricing Plans API. - name: _id | type: string | description: Plan GUID. | read-only: true | validation: format GUID - name: revision | type: string | description: Revision number, which increments by 1 each time the plan is updated. | read-only: true | validation: format int64 - name: _createdDate | type: Date | description: Date and time the plan was created. | read-only: true - name: _updatedDate | type: Date | description: Date and time the plan was last updated. | read-only: true - name: name | type: string | description: Plan name displayed to customers. | validation: minLength 1, maxLength 50 - name: description | type: string | description: Plan description that explains what customers get with this plan. | validation: maxLength 450 - name: image | type: string | description: Plan image displayed during checkout and on the site's **Plans & Pricing** page. - name: slug | type: string | description: Unique identifier for this plan within the Wix site. If not provided, generated automatically from the plan name. | validation: maxLength 255, format URL_SLUG - name: termsAndConditions | type: string | description: Terms and conditions text that customers must agree to when purchasing this plan. | validation: maxLength 3000 - name: pricingVariants | type: array | description: Pricing variants that define different billing and pricing options for this plan. Currently limited to 1 variant per plan. | validation: minItems 1, maxItems 20 - name: _id | type: string | description: Pricing variant GUID. | validation: format GUID - name: name | type: string | description: Name for this pricing variant, such as "Monthly" or "Yearly". | validation: minLength 1, maxLength 255 - name: freeTrialDays | type: integer | description: Number of days customers can use the plan for free before the first charge. Set to `0` for no free trial. | validation: minimum 0, maximum 999 - name: fees | type: array | description: Additional fees applied to this pricing variant. | validation: maxItems 5 - ONE-OF: - name: fixedAmountOptions | type: FixedAmountOption | description: Fixed monetary amount for the fee. - name: amount | type: string | description: Fixed monetary amount. | validation: decimalValue {"gt":"0","maxScale":4} - name: _id | type: string | description: | validation: format GUID - name: priceType | type: PriceType | description: Pricing type used for this fee. - enum: - FIXED_AMOUNT: Fee is charged as a fixed monetary amount. - name: name | type: string | description: Fee name displayed to customers, such as "Setup Fee" or "Processing Fee". | validation: minLength 1, maxLength 40 - name: appliedAt | type: AppliedAt | description: When this fee is charged during the customer's plan lifecycle. - enum: - FIRST_PAYMENT: Fee is added to the first payment. - name: billingTerms | type: BillingTerms | description: Billing configuration that defines when and how often customers are charged. - ONE-OF: - name: cyclesCompletedDetails | type: CyclesCompletedDetails | description: How many billing cycles the plan lasts. - name: billingCycleCount | type: string | description: Number of billing cycles before the plan automatically ends. For example, if `billingCycle` is 3 months and `billingCycleCount` is 4, the customer will be charged 4 times over 12 months before the plan expires. Only applicable if `endType` is `CYCLES_COMPLETED`. | validation: minimum 1, maximum 2000 - name: billingCycle | type: Duration | description: Duration of each billing cycle, such as 1 month or 2 weeks. Can't be less than 7 days. Only applicable for recurring plans. - name: period | type: Period | description: Duration of period. - enum: DAY, WEEK, MONTH, YEAR - name: count | type: string | description: Number of periods. | validation: minimum 1 - name: startType | type: StartType | description: When the billing starts. - enum: - ON_PURCHASE: Billing starts immediately after purchase. - CUSTOM: Customer can choose when billing starts. - name: endType | type: EndType | description: How long the plan remains active. Plans can run until canceled or for a specific number of billing cycles. Plan duration can't exceed 10 years. - enum: - UNTIL_CANCELLED: Plan continues until customer cancels. - CYCLES_COMPLETED: Plan ends after a specified number of billing cycles. - name: promotion | type: string | description: Promotional message displayed with this pricing variant. | validation: maxLength 255 - name: pricingStrategies | type: array | description: Pricing strategies that determine how much customers pay. Currently limited to 1 strategy per variant. | validation: minItems 1, maxItems 1 - ONE-OF: - name: flatRate | type: FlatRate | description: Single fixed cost charged regardless of usage. - name: amount | type: string | description: Fixed monetary amount. | validation: decimalValue {"gte":"0","maxScale":4} - name: visible | type: boolean | description: Whether this pricing variant is visible to customers. Defaults to `true` when not set. At least one variant per plan must remain visible. Variant-level visibility is independent from plan-level visibility (`Plan.visibility`). - name: categoryIds | type: array | description: IDs of the categories this variant belongs to. Categories group variants across plans (for example into a "Monthly / Yearly" selector) independently of billing cycle. Optional. | validation: maxItems 1, format GUID - name: priceOverrides | type: PriceOverrides | description: Rules that override this pricing variant's price for purchases that meet their conditions. Applied during purchase. An override that matches the purchase always replaces the variant's original price, even when the resulting price is higher. If multiple overrides match the same purchase, the lowest resulting price among them wins - the original price doesn't participate in this comparison. The overridden price applies to every billing cycle of the resulting subscription, not only the first payment. Updates replace the entire list of overrides. To remove all overrides, set this field to `null` - an empty overrides list isn't accepted. - name: overrides | type: array | description: Price override rules. | validation: minItems 1, maxItems 10 - ONE-OF: - name: fixedPriceOptions | type: FixedPriceOptions | description: Options for the `FIXED_PRICE` override type. - name: amount | type: string | description: Price that replaces the pricing variant's original price. Can be higher than the original price. | validation: decimalValue {"gte":"0","maxScale":4} - name: percentageDiscountOptions | type: PercentageDiscountOptions | description: Options for the `PERCENTAGE_DISCOUNT` override type. - name: percentage | type: string | description: Percentage to deduct from the pricing variant's original price. For example, `12.5` for a 12.5% discount. The discounted price is rounded to the number of decimal places supported by the plan's currency. | validation: decimalValue {"gt":"0","lte":"100","maxScale":2} - name: _id | type: string | description: Price override GUID. Must be unique within the pricing variant. | validation: format GUID - name: conditions | type: PurchaseConditions | description: Conditions a purchase must meet for this override to apply. - ONE-OF: - name: specificMembersOptions | type: SpecificMembersOptions | description: Options for the `SPECIFIC_MEMBERS` customer eligibility. - name: memberIds | type: array | description: IDs of the members the override applies to. The logged-in buyer must be one of these members. | validation: minItems 1, maxItems 50, format GUID - name: customerEligibility | type: CustomerEligibility | description: Which customers the override applies to. - enum: - ALL: The override applies to all customers. - RETURNING: The override applies only to returning customers - members with at least 1 plan subscription on the site, counted across all plans by the member's contact. Pending, active, paused, ended, and canceled subscriptions count; draft subscriptions don't. - SPECIFIC_MEMBERS: The override applies only to the specified members. - name: validFromDate | type: Date | description: Date and time from which the override applies. The purchase must happen on or after this exact instant. When `valid_until_date` is also set, must be earlier than `valid_until_date` - equal values are rejected. - name: validUntilDate | type: Date | description: Date and time until which the override applies. The purchase must happen before this exact instant. - name: overrideType | type: OverrideType | description: How the pricing variant's price is overridden. - enum: - FIXED_PRICE: The pricing variant's price is replaced with a fixed price. - PERCENTAGE_DISCOUNT: The pricing variant's price is reduced by a percentage. - name: feeOverrides | type: FeeOverrides | description: Rules that override specific fees of this pricing variant for purchases that meet their conditions. Applied during purchase. If multiple overrides apply to the same fee, the lowest resulting fee amount wins, with a waived fee counting as `0`. Updates replace the entire list of overrides. To remove all overrides, set this field to `null` - an empty overrides list isn't accepted. - name: overrides | type: array | description: Fee override rules. | validation: minItems 1, maxItems 10 - ONE-OF: - name: fixedAmountOptions | type: FixedAmountOptions | description: Options for the `FIXED_AMOUNT` override type. - name: amount | type: string | description: Amount that replaces the fee's original amount. Must be greater than `0`. To remove the fee from the purchase, use the `WAIVED` override type instead. | validation: decimalValue {"gt":"0","maxScale":4} - name: _id | type: string | description: Fee override GUID. Must be unique within the pricing variant. | validation: format GUID - name: feeId | type: string | description: GUID of the fee on the same pricing variant that this override applies to. | validation: format GUID - name: conditions | type: PurchaseConditions | description: Conditions a purchase must meet for this override to apply. - name: overrideType | type: OverrideType | description: How the fee is overridden. - enum: - FIXED_AMOUNT: The fee's amount is replaced with a fixed amount. - WAIVED: The fee isn't applied to the purchase at all. - name: perks | type: array | description: List of text snippets describing what the plan offers. For display purposes only. | validation: maxItems 500 - name: _id | type: string | description: Perk GUID. | validation: format GUID - name: description | type: string | description: Perk description. | validation: minLength 1, maxLength 1400 - name: visibility | type: Visibility | description: Plan visibility. - enum: - PUBLIC: Plan is visible and available for purchase by all customers. - PRIVATE: Plan isn't visible to new customers unless they get a specific link to the plan. Existing buyers can continue using it. - name: buyable | type: boolean | description: Whether customers can currently purchase this plan. If set to `false`, customer won't be able to buy a plan themselves. In this case a Wix user has to assign the plan through the [dashboard](https://support.wix.com/en/article/pricing-plans-selling-plans-offline). - name: formId | type: string | description: GUID of the form associated with the plan at checkout. | validation: format GUID - name: buyerCanCancel | type: boolean | description: Whether buyers can cancel their subscription to this plan. - name: currency | type: string | description: Three-letter currency code in [ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. When the site currency changes, monetary amounts stored on the plan (prices, fees, and override amounts) are automatically rounded to the number of decimal places supported by the new currency. | read-only: true | validation: format CURRENCY - name: purchaseLimits | type: array | description: Caps how many subscriptions buyers can have or the site can sell for this plan. When multiple types are present, all must pass (AND logic). Duplicate types are rejected by the server. | validation: maxItems 4 - name: type | type: PurchaseLimitType | description: The type of purchase limit. - enum: - PER_MEMBER_LIFETIME: Limits the total number of subscriptions (any status) a single member can have over their lifetime. - PER_MEMBER_ACTIVE: Limits the number of ongoing (ACTIVE, PENDING, PAUSED) subscriptions a single member can have at any time. - TOTAL_ACTIVE: Limits the total number of ongoing (ACTIVE, PENDING, PAUSED) subscriptions across all members at any time. - TOTAL_SOLD: Limits the total number of subscriptions ever created (any status) across all members. - name: maxCount | type: integer | description: The maximum number of subscriptions allowed. | validation: minimum 1, maximum 10000 - name: benefitDistributionSettings | type: BenefitDistributionSettings | description: The settings of the benefit distribution for subscriptions to this plan - ONE-OF: - name: customScheduleOptions | type: CustomScheduleOptions | description: Custom schedule - name: cycleDuration | type: Duration | description: Cycle duration - name: unit | type: DurationUnit | description: Duration unit: DAY, WEEK, MONTH, YEAR - enum: UNKNOWN, DAY, WEEK, MONTH, YEAR - name: count | type: integer | description: Amount of units. For example, 1 MONTH, 1 YEAR, 2 WEEKS, etc. Optional. Default is 1. | validation: minimum 1, format int32 - name: distributionStrategyType | type: DistributionStrategyType | description: The distribution strategy of the benefits for this subscription, which is used to determine how the benefits are distributed in each cycle. - enum: UNKNOWN_DISTRIBUTION_STRATEGY_TYPE, PER_BILLING_CYCLE, CUSTOM_SCHEDULE - name: startDateSettings | type: StartDateSettings | description: Settings that control when subscriptions to this plan start. Applied during purchase to calculate the subscription start date and validate customer-selected start dates. The settings apply only to pricing variants with a compatible `billing_terms.start_type`: `FIXED_DATE` and `DAY_OF_MONTH` apply to variants with the `ON_PURCHASE` start type, while `DATE_RANGE` applies to variants with the `CUSTOM` start type. - ONE-OF: - name: fixedDateOptions | type: FixedDateOptions | description: Subscription starts on the earliest of the configured fixed dates that hasn't passed. - name: startDates | type: array | description: Dates on which a subscription can start. A purchase starts the subscription on the earliest listed date that hasn't passed in the site's time zone. A purchase made on one of the dates starts the subscription immediately. When every date has passed the plan can't be purchased and `start_date_unavailable_message` is displayed. Only the calendar date in the site's time zone is used, the time of day is ignored. Order doesn't matter. Dates must be unique. | validation: maxItems 5 - name: dayOfMonthOptions | type: DayOfMonthOptions | description: Subscription starts on a specific day of each month. - name: dayOfMonth | type: integer | description: Day of the month the subscription starts. For months with fewer days, the subscription starts on the last day of the month. If the purchase happens on the configured day, the subscription starts on that same day. Only determines the subscription start date - subsequent billing cycles follow the pricing variant's `billing_terms.billing_cycle` from that start date. | validation: minimum 1, maximum 31 - name: dateRangeOptions | type: DateRangeOptions | description: Customer selects a start date within a date range. - name: startDate | type: Date | description: Date and time from which the customer can select the subscription start date. The selected start date must be on or after this exact instant. - name: endDate | type: Date | description: Date and time until which the customer can select the subscription start date. If not set, the range is open-ended. The selected start date must be before this exact instant. Must be later than `start_date`. - name: type | type: StartDateType | description: How the subscription start date is determined. - enum: - FIXED_DATE: Subscription starts on the earliest of the configured fixed dates that hasn't passed. Applies only to pricing variants with the `ON_PURCHASE` start type. - DAY_OF_MONTH: Subscription starts on a specific day of each month. Applies only to pricing variants with the `ON_PURCHASE` start type. - DATE_RANGE: Customer selects a start date within a date range. Applies only to pricing variants with the `CUSTOM` start type. - name: startDateUnavailableMessage | type: string | description: Message displayed to customers when no start date is available. For example, when every fixed start date or the end of the date range has passed. Applicable only when `type` is `FIXED_DATE`, or `DATE_RANGE` with `date_range_options.end_date` set - in other configurations a start date is always available and the message is ignored. | validation: minLength 1, maxLength 512 - name: tags | type: Tags | description: Tags that can be assigned to this plan for classification and filtering. - name: privateTags | type: TagList | description: Tags that require an additional permission in order to access them, normally not given to site members or visitors. - name: tagIds | type: array | description: List of tag GUIDs | validation: maxItems 100, maxLength 5 - name: publicTags | type: TagList | description: Tags that are exposed to anyone who has access to the labeled entity itself, including site members and visitors. - name: extendedFields | type: ExtendedFields | description: Data extensions. Learn more about [extended fields](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md). - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). | validation: format map - name: nextStartDate | type: Date | description: Date the plan becomes active when purchased now. Returned only when at least one available variant has `ON_PURCHASE` start type and a start date rule is configured. Absent in two cases: the plan starts immediately on purchase, or the buyer chooses the start date. Check the variant's `billing_terms.start_type` to tell which. - name: benefitInfo | type: BenefitInfo | description: Benefit that grants access to the item. - name: externalId | type: string | description: GUID of the item in the provider app's own system. For example, if the benefit items are products, this GUID corresponds to the specific product GUID in the provider's system. | read-only: true | validation: format GUID, immutable - name: category | type: string | description: Item category. Groups benefit items together for organization and management purposes. For example, classes, posts, groups. Always the same value passed in `item_identifier.category`. Categories are defined by the provider app, not by Wix. An empty string means the item has no category. | read-only: true | validation: maxLength 20, immutable - name: providerAppId | type: string | description: GUID of the application providing the benefit item. GUID of the external application supplying the items. Each item's external GUID is unique to its respective provider's application. | read-only: true | validation: format GUID, immutable - name: poolDefinitionId | type: string | description: GUID of the Benefit Programs pool definition that this benefit belongs to. Use together with `benefit_key` to identify a benefit. | read-only: true | validation: format GUID, immutable - name: itemSetId | type: string | description: Link between the benefit outlined in a pool definition and the specific item included in that benefit. Defined by the Benefit Programs API. To identify a benefit, use `pool_definition_id` together with `benefit_key`. | read-only: true | validation: format GUID, immutable - name: price | type: string | description: Price of the benefit, expressed in the credit unit given by `credit_configuration.unit_type`. The price is the same for all of this benefit's items. Not a currency amount. | validation: decimalValue {"gte":"0","maxScale":4} - name: creditConfiguration | type: CreditConfiguration | description: Credit settings of the pool that this benefit belongs to. When absent, benefits do not support credit-based pricing. - name: amount | type: string | description: Number of credits granted when the plan is purchased, expressed in `unit_type`. This is the starting balance and doesn't reflect credits already used. | validation: decimalValue {"gte":"0","maxScale":4} - name: unitDisplayName | type: string | description: Name of the credit unit to display to buyers. For example, `Sessions`. | validation: maxLength 32 - name: unitType | type: string | description: Machine-readable credit unit type. For example, `PUNCH_CARD`. Defined by the provider app rather than by a fixed Wix set, so treat it as opaque. Use `unit_display_name` for anything shown to buyers. | validation: maxLength 16 - name: benefitKey | type: string | description: Identifier of the benefit, unique within its pool definition. Stable across requests, so it's safe to store and compare. The format is defined by the provider app, so treat it as opaque. | validation: maxLength 64 - name: displayName | type: string | description: Benefit name. | validation: maxLength 40 - name: description | type: string | description: Benefit description. | validation: maxLength 255 ``` ### Examples ### List plans by item identifier Retrieves the pricing plans a customer can purchase in order to use a specific item, such as a class or a session, together with the benefit that grants access to it. ```javascript import { planBenefits } from "@wix/pricing-plans"; async function listPlansByItemIdentifier() { const response = await planBenefits.listPlansByItemIdentifier( { externalId: "c0b0bd57-ff8e-4525-a577-04796b22cd60", providerAppId: "13d21c63-b5ec-5912-8397-c3a5ddb27a97", }, { targetDate: new Date("2026-10-06T09:00:00.000Z"), count: 1, }, ); } /* Promise resolves to: * { * "planBenefits": [ * { * "planInfo": { * "plan": { * "_id": "3d01efce-6159-4012-8e30-25fbbdaa7385", * "_createdDate": "2026-08-12T10:59:08.450Z", * "_updatedDate": "2026-09-01T20:48:52.010Z", * "revision": "4", * "name": "10 Class Pass", * "description": "Ten yoga classes to use over six months.", * "slug": "10-class-pass", * "pricingVariants": [ * { * "_id": "adc8516b-5dbd-455d-bec5-af5c234459d6", * "name": "Monthly", * "freeTrialDays": 0, * "billingTerms": { * "billingCycle": { "period": "MONTH", "count": "1" }, * "startType": "ON_PURCHASE", * "endType": "CYCLES_COMPLETED", * "cyclesCompletedDetails": { "billingCycleCount": "6" } * }, * "pricingStrategies": [{ "flatRate": { "amount": "10" } }], * "visible": true * } * ], * "perks": [ * { * "_id": "6f0f2cc4-32a3-4b1e-9a3c-5e4f4e0b6d21", * "description": "Book any yoga class in the studio schedule." * } * ], * "visibility": "PUBLIC", * "buyable": true, * "buyerCanCancel": true, * "currency": "USD", * "purchaseLimits": [{ "type": "PER_MEMBER_ACTIVE", "maxCount": 1 }] * } * }, * "benefitInfo": { * "externalId": "c0b0bd57-ff8e-4525-a577-04796b22cd60", * "category": "", * "providerAppId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97", * "poolDefinitionId": "dad32883-a91a-4c42-ac33-81f08755a0d6", * "itemSetId": "85d84686-e709-4dce-b1d9-1e21dbb41ff4", * "price": "1", * "creditConfiguration": { * "amount": "10", * "unitDisplayName": "Sessions", * "unitType": "PUNCH_CARD" * }, * "benefitKey": "01", * "displayName": "Recurring Class", * "description": "10 sessions" * } * }, * { * "planInfo": { * "plan": { * "_id": "e26f7214-eb6b-403c-b366-2ebaf3993653", * "_createdDate": "2026-07-03T21:15:47.650Z", * "_updatedDate": "2026-07-04T14:54:38.276Z", * "revision": "3", * "name": "Unlimited Studio Membership", * "description": "Unlimited access to every class in the studio.", * "slug": "unlimited-studio-membership", * "pricingVariants": [ * { * "_id": "149c5d00-d263-4e82-a345-f437f0cf3f3f", * "name": "Every 6 months", * "freeTrialDays": 0, * "billingTerms": { * "billingCycle": { "period": "MONTH", "count": "6" }, * "startType": "ON_PURCHASE", * "endType": "UNTIL_CANCELLED" * }, * "pricingStrategies": [{ "flatRate": { "amount": "120" } }], * "visible": true * } * ], * "visibility": "PUBLIC", * "buyable": true, * "buyerCanCancel": true, * "currency": "USD" * }, * "nextStartDate": "2026-10-05T00:00:00.000Z" * }, * "benefitInfo": { * "externalId": "c0b0bd57-ff8e-4525-a577-04796b22cd60", * "category": "", * "providerAppId": "13d21c63-b5ec-5912-8397-c3a5ddb27a97", * "poolDefinitionId": "9c740343-920c-417a-a9b0-768b6973bdaf", * "itemSetId": "a420004a-5a83-403c-8b15-d98f3a09c3be", * "benefitKey": "afdfd390-55bb-409c-a948-9826c7dff299", * "displayName": "Unlimited Classes" * } * } * ] * } */ ``` ### listPlansByItemIdentifier (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 { planBenefits } from '@wix/pricing-plans'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { planBenefits }, // Include the auth strategy and host as relevant }); async function listPlansByItemIdentifier(itemIdentifier,options) { const response = await myWixClient.planBenefits.listPlansByItemIdentifier(itemIdentifier,options); }; ``` ---