About the Plan Benefits API

The Plan Benefits API tells you which pricing plans a customer can purchase in order to use a specific item, such as a class or a session. For each plan it also returns the benefit that grants access to that item.

With the Plan Benefits API, you can retrieve the purchasable plans that cover a given item, narrowed to the pricing variants a customer can actually buy, together with what the item costs in that plan's credits.

Call the API with an item identifier supplied by the app that provides the item, for example Wix Bookings for a class. Only plans that are public and not archived are considered, and each returned plan carries just the pricing variants available for purchase. A variant is dropped when the target date is in the past, falls outside the plan's duration, or falls outside the plan's start date limits. A plan is dropped entirely when the member has reached its purchase limits or when none of its variants survive, and so is a benefit whose credit price can't cover the number of items requested.

Plan availability and the customer's identity

Plan availability is evaluated for the member the call is made for. When there's no member, per-member purchase limits are skipped and only site-wide limits apply, so the same customer can see a plan as a visitor that disappears once they sign in.

Returned prices reflect any pricing overrides active for the current context, so they can differ from the same plan retrieved from the Pricing Plans API.

Before you begin

It's important to note the following points before starting to code:

• The site must have the Pricing Plans app installed, and the item's provider app must have at least one benefit that covers the item.
• The API is called on behalf of a site visitor or member, or with an app identity. It isn't available to Wix users, so it can't be called with a dashboard identity.
• itemIdentifier.category is matched exactly and isn't a wildcard when omitted. If the provider app stores a category for its items, you must pass it.
• Target dates are evaluated as calendar days in the site's time zone, or in UTC when the site has no time zone, so the time-of-day part of targetDate is ignored.
• A plan is returned once for every benefit that covers the item, so the same plan can appear more than once with different benefit details.

Use cases

• Offer a customer the plans that unlock a specific session

Terminology

• Plan: A pricing plan that defines what customers can purchase and how they'll be charged, including billing terms, pricing, and features. Returned as planInfo.plan.
• Benefit: An entitlement within a pool that offers products or services at a designated price in credits. Not to be confused with an item. Returned as benefitInfo; use poolDefinitionId together with benefitKey to identify one.
• Item: A reference to a reward, product, or service provided by another app. This is what you ask about, identified by externalId, providerAppId, and category. The same item can be covered by several benefits, which is why a plan can be returned more than once.
• Item set: The link between a benefit outlined in a pool definition and the specific items included in that benefit. Surfaced as itemSetId, but not the developer-facing identifier. Use poolDefinitionId and benefitKey instead.
• Provider app: The 3rd-party app supplying the items. Identified by providerAppId. Item IDs are defined by the provider app, so they're only unique within it.
• Category: A label the provider app uses to group items by type, for example class, post, or group.
• Credit: The unit a benefit is priced in, configured on the pool definition. Used in benefitInfo.price when the benefit has credit-based pricing, and described by creditConfiguration.

For a comprehensive glossary of benefit terms, see the Benefit Programs terminology.