> 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

# queryPlans

# Package: @wix/pricing-plans

# Namespace: plansV3

# Method link: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/query-plans.md

## Permission Scopes:
Read Orders: SCOPE.DC-PAIDPLANS.READ-ORDERS
Read Pricing Plans: SCOPE.DC-PAIDPLANS.READ-PLANS

## Introduction

Retrieves a list of plans, given the provided paging, filtering, and sorting.
Query plans runs with these defaults, which you can override:
- `createdDate` is sorted in `ASC` order
- `cursorPaging.limit` is `100`
<br>
To learn about working with queries, see [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language).

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.pricingPlans.plansV3.queryPlans(query)
 Description: Retrieves a list of plans, given the provided paging, filtering, and sorting. Query plans runs with these defaults, which you can override: - `createdDate` is sorted in `ASC` order - `cursorPaging.limit` is `100` <br> To learn about working with queries, see [API Query Language](https://dev.wix.com/api/rest/getting-started/api-query-language).
 # 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: query | type: PlanQuery   | 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.  | validation: minimum 0, maximum 100, format int32
        - 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.  | validation: maxLength 16000
        - name: filter | type: object | description: Filter object.  Learn more about [filtering](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md#filters).  
        - name: sort | type: array<Sorting> | description: Sort object.  Learn more about [sorting](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md#sorting).  | validation: maxItems 5
           - name: fieldName | type: string | description: Name of the field to sort by.  | validation: maxLength 512
           - name: order | type: SortOrder | description: Sort order.  
                 - enum: ASC, DESC
 Query fields:
   - field: pricingVariants.pricingStrategies.flatRate.amount | operators: $hasSome, $hasAll | sort: none | aggregatable: undefined | searchable: undefined
   - field: _id | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte, $startsWith | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: _createdDate | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: _updatedDate | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: name | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte, $startsWith | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: visibility | operators: $eq, $ne, $in, $exists | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: formId | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte, $startsWith | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: slug | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte, $startsWith | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: termsAndConditions | operators: $eq, $ne, $in, $exists, $gt, $gte, $lt, $lte, $startsWith | sort: ASC, DESC | aggregatable: undefined | searchable: undefined
   - field: pricingVariants.categoryIds | operators: $hasSome, $hasAll, $exists, $isEmpty | sort: none | aggregatable: undefined | searchable: undefined
   - field: pricingVariants._id | operators: $hasSome, $hasAll | sort: none | aggregatable: undefined | searchable: undefined
   - field: pricingVariants.name | operators: $hasSome, $hasAll | sort: none | aggregatable: undefined | searchable: undefined
   - field: tags.publicTags.tagIds | operators: $hasSome, $hasAll | sort: none | aggregatable: undefined | searchable: undefined
   - field: tags.privateTags.tagIds | operators: $hasSome, $hasAll | sort: none | aggregatable: undefined | searchable: undefined
 Return type: PROMISE<QueryPlansResponse>
  - name: plans | type: array<Plan> | description: List of plans.  
     - 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<PricingVariant> | 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<Fee> | 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<PricingStrategy> | 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<string> | 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<PriceOverride> | 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<string> | 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<FeeOverride> | 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<Perk> | 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<PurchaseLimit> | 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<string> | 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: pagingMetadata | type: PagingMetadataV2 | description: Paging metadata.  
     - name: count | type: integer | description: Number of items returned in the response.  | validation: format int32
     - name: offset | type: integer | description: Offset that was requested.  | validation: format int32
     - name: total | type: integer | description: Total number of items that match the query. Returned if offset paging is used and the `tooManyToCount` flag is not set.  | validation: format int32
     - name: tooManyToCount | type: boolean | description: Flag that indicates the server failed to calculate the `total` field.  
     - name: cursors | type: Cursors | description: Cursors to navigate through the result pages using `next` and `prev`. Returned if cursor paging is used.  
        - name: next | type: string | description: Cursor string pointing to the next page in the list of results.  | validation: maxLength 16000
        - name: prev | type: string | description: Cursor pointing to the previous page in the list of results.  | validation: maxLength 16000


```

### Examples

### Query plans
```javascript
import { plansV3 } from "@wix/pricing-plans";

async function queryPlans() {
  const response = await plansV3
    .queryPlans()
    .eq("visibility", "PUBLIC")
    .ascending("name")
    .limit(10)
    .find();
}

/* Promise resolves to:
 * {
 *   "_items": [
 *     {
 *       "_id": "5d1c47f5-0ec7-4c9c-9f9c-a87be388e3f9",
 *       "revision": "1",
 *       "name": "Professional Studio",
 *       "pricingVariants": [
 *         {
 *           "_id": "6304bd66-128e-454e-8c95-e389b78cc7e1",
 *           "name": "Monthly",
 *           "billingTerms": {
 *             "billingCycle": {
 *               "period": "MONTH",
 *               "count": "1"
 *             },
 *             "startType": "ON_PURCHASE",
 *             "endType": "UNTIL_CANCELLED"
 *           },
 *           "pricingStrategies": [
 *             {
 *               "flatRate": {
 *                 "amount": "5.99"
 *               }
 *             }
 *           ]
 *         }
 *       ],
 *       "visibility": "PUBLIC",
 *       "buyable": true,
 *       "buyerCanCancel": true,
 *       "currency": "EUR"
 *     }
 *   ],
 *   "cursors": {}
 * }
 */

```

### queryPlans (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 { plansV3 } from '@wix/pricing-plans';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { plansV3 },
  // Include the auth strategy and host as relevant
});


async function queryPlans(query) {
  const response = await myWixClient.plansV3.queryPlans(query);
};
```

---