About Pricing Plans

Use the Pricing Plans API to create and manage your plans and orders. With Pricing Plans, you can build a customized membership plan experience.

With the Pricing Plans API, you can:

• Get and manage plans.
• Get and manage orders.

To use Pricing Plans APIs to manage your plans, first set up your site to:

• Accept payments as described in About Accepting Payments.

• Offer membership plans as described in About Pricing Plans. When setting up your site to accept pricing plans, define the plans you want to offer using the Dashboard or using the Pricing Plan APIs.

Pricing models

Pricing models contain the pricing and duration options for a plan.

Plans are based on a pricing model, which is defined with the plan's pricing property. A pricing model can be one of the following:

• A subscription: A plan with recurring payment cycles.

Example: A 1-year subscription with monthly, recurring payments. Each payment is $25, so the total price for the plan is $300. In this example, the subscription is in its third month.

cycleDuration is the length of one payment cycle. Multiply cycleDuration's count by cycleCount to get the subscription duration. Currently, cycleDuration only supports a value of 1.

index of currentCycle is the current payment cycle for the subscription. index is 0 when the order is in a free trial period. In all other cases, the index starts with 1 for the first payment cycle in the subscription. For orders with a single payment, the index will remain 1 throughout the duration.

1
"pricing": {
2
        "subscription": {
3
            "cycleDuration": {
4
                // Payment recurs every month
5
                "count": 1,
6
                "unit": "MONTH"
7
            },
8
            // for 12 times
9
            "cycleCount": 12
10
        },               
11
        "prices": [{              
12
            "duration": {
13
                "cycleFrom": 1,
14
                "numberOfCycles": 12
15
            },
16
            "price": {
17
                "subtotal": "25",
18
                "discount": "0",
19
                "total": "25",
20
                "currency": "USD"
21
            }
22
        }]
23
    }, 
24
    ...
25
    "currentCycle": {
26
        "index": 3,
27
        "startedDate": "2022-03-01T13:45:53.129Z",
28
        "endedDate": "2022-04-01T13:45:53.129Z"
29
    },

• A Single Payment for Duration plan: A plan paid for with a single payment. The plan does not renew after the duration.

Example: A plan with a single payment of $35 for 3 months.

The duration cycleFrom and numberOfCycles will both be 1, as the single price applies to the entirety of the subscription.

index of currentCycle will remain 1 throughout the duration.

1
"pricing": {
2
        "singlePaymentForDuration": {
3
            // Plan duration is 3 months
4
            "count": 3,
5
            "unit": "MONTH"
6
        },
7
        "prices": [{              
8
            "duration": {
9
                "cycleFrom": 1,
10
                "numberOfCycles": 1
11
            },
12
            "price": {
13
                "subtotal": "35",
14
                "discount": "0",
15
                "total": "35",
16
                "currency": "USD"
17
            }
18
        }]
19
    },
20
    ...
21
    "currentCycle": {
22
        "index": 1,
23
        "startedDate": "2022-01-01T13:45:53.129Z",
24
        "endedDate": "2022-04-01T13:45:53.129Z"
25
    },

• A Single Payment Unlimited plan: A plan paid for with a single payment. The plan does not expire and remains valid until canceled.

Example: An unlimited plan that is paid for in advance with one payment of $200.

singlePaymentUnlimited is true.

The duration cycleFrom and numberOfCycles will remain 1 throughout the duration of the plan.

index of currentCycle will remain 1 throughout the duration. singlePaymentUnlimitedPlans don't return an endedDate in currentCycle.

1
"pricing": {
2
        "singlePaymentUnlimited": true,
3
        "prices": [{
4
            "duration": {
5
                "cycleFrom": 1,
6
                "numberOfCycles": 1
7
            },                
8
            "price": {
9
                "subtotal": "200",
10
                "discount": "0",
11
                "total": "200",
12
                "currency": "USD"
13
            }
14
        }]
15
    },
16
    ...
17
    "currentCycle": {
18
        "index": 1,
19
        "startedDate": "2021-06-015T13:45:53.129Z"
20
    },

Free plans and free trial periods

A free plan that is valid until canceled is a singlePaymentUnlimited pricing model. A free plan with a limited duration is treated as a singlePaymentForDuration pricing model.

A site owner can also add a free trial period, in days, to a subscription pricing model. When the free trial is over, the first payment cycle begins and the buyer is billed. During the free trial period, the index of currentCycle is 0. A buyer only receives the free trial period for the first time they purchase a plan. For example, a buyer purchases a monthly plan for 3 months that includes a 7-day free trial period. The buyer may purchase the same plan again, for another 3 months, but will not receive the 7-day free trial period.

When a buyer cancels their order during the free trial period, their subscription will expire at the end of the free trial period and they will not be billed. A site owner can cancel an ordered plan during the free trial period and choose to apply the cancellation IMMEDIATELY or at the NEXT_PAYMENT_DATE.

Canceling IMMEDIATELY ends the subscription for the buyer immediately, even during the free trial period, and the buyer won't be billed. Canceling at the NEXT_PAYMENT_DATE allows the buyer to continue using the benefits of the subscription until the end of the free trial period. Then, the subscription ends and the buyer is not billed.

Pricing plan types and visibility

• Public pricing plans are visible plans that site members and visitors can see on the site and purchase. By default, pricing plans are public when created.

• Hidden pricing plans are plans whose public property has been set to false. These plans cannot be seen on the site by the site member or visitor. For example, consider hiding a plan if it has reached its maximum capacity and temporarily is not available for purchase.

  Changing a plan’s visibility with the public property does not impact existing purchases. All purchases for hidden plans are still active and keep their terms and payment options.

• Active pricing plans include all non-archived plans, such as public plans and hidden plans.

• Archived pricing plans are plans that are no longer needed on the site. For example, discontinued plans. When a plan is archived, it is no longer visible as a public plan that can be chosen by site visitors.

The public property is automatically set to false when a plan is archived. Archived plans cannot be purchased.

Site owners can see archived plans in the Dashboard under Pricing Plans -> Archived Plans.

Archiving cannot be reversed. Once archived, a plan cannot be set as active again for purchase. Archiving does not impact existing purchases made for the plan. All purchases are still active and keep their pricing and terms.

Orders and subscriptions

Actions related to basic pricing plan management are available from the Pricing Plans page in the Dashboard. These actions correspond to the functions available in the Pricing Plans APIs.

Every pricing plan order corresponds to a Wix subscription, including orders for single payment plans. You can see all orders from your site's Subscriptions page in the Dashboard. Actions available on this page correspond to the functions available in the Orders APIs.

Terminology

• Plan: Type of plan, including: One-time Payment, Recurring Payment, or Free/Trial.
• Pricing Models: The pricing and duration options for a plan.
  • Subscription: A plan with recurring payment cycles.
  • Single Payment For Duration: A set plan that does not renew, paid for with a single payment.
  • Single Payment Unlimited: An unlimited plan, paid for with a single payment. The plan does not expire and remains valid until canceled.
• Free Trial: A plan's free trial period that can be added to a subscription pricing model.
• Free Plan: A free plan that is valid until canceled (single payment unlimited), or a free plan with a limited duration (single payment for duration).
• Orders: A member's order or purchase of a pricing plan. An order can be made:
  • Online: When members order and pay for their plans without manual intervention.
  • Offline: When members place their order by phone, text, or email.