About the Pricing Plans Settings API

The Pricing Plans Settings API lets you read and update the site-level settings that govern how pricing plans are sold on a site. A site has a single Pricing Plans settings object, and it applies to every plan on the site.

With the Pricing Plans Settings API, you can:

• Set which of the site's addresses tax is calculated from for plan purchases.
• Allow or block site visitors from purchasing a plan without signing in as a site member.
• Turn automatic invoicing on or off for plan payments.

Settings you can update

These settings are writable with Update Pricing Plans Settings:

• taxableAddress: Which address determines the tax jurisdiction for a plan purchase. BILLING uses the buyer's billing address, supplied at checkout. BUSINESS uses the site owner's business address, configured in the site's business info. Buyers see the resulting tax amount on the plan's line item.
• guestCheckoutSettings.enabled: Whether a site visitor can buy a plan without signing in as a site member. The requirement is site-wide, so while it's disabled, buying any plan requires signing in.
• invoiceSettings.sendInvoiceOnPayment: Whether an invoice is automatically created and sent to the buyer each time an online payment for a plan succeeds. Applies only to subscriptions that weren't purchased with the eCommerce APIs.

Site owners set the same values without code, on the Pricing Plans Settings page in the site dashboard:

• taxableAddress corresponds to the tax setting. See setting up tax collection.
• guestCheckoutSettings.enabled corresponds to the guest checkout toggle on the Checkout tab. See allowing guest checkout.
• invoiceSettings.sendInvoiceOnPayment corresponds to the Send Invoices toggle on the Billing tab. See automatically creating invoices.

A change made with this API shows up in the dashboard, and a change made in the dashboard is returned by this API.

Defaults and when changes take effect

A site that hasn't been configured yet gets the default settings: taxableAddress is BILLING, guestCheckoutSettings.enabled is false, and invoiceSettings.sendInvoiceOnPayment is false. Defaults are returned without being stored, so an update that passes the revision from such a response can fail.

A settings change doesn't affect a checkout that's already been rendered. Tax for that purchase is calculated from the value read before the change.

Automatic invoicing applies to online payments for subscriptions that weren't purchased with the eCommerce APIs.

Before you begin

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

• The Wix user must install the Wix Pricing Plans app on their site.
• A site's Pricing Plans settings are created automatically when the app is installed. There's no create step, and Get Pricing Plans Settings never returns NOT_FOUND.
• A site has a single Pricing Plans settings object, and it can't be deleted.
• Before setting taxableAddress to BUSINESS, confirm the site has a business address. Without one, plan purchases fail until an address is added.

Use cases

• Configure tax handling for pricing plan purchases
• Let visitors buy a plan without signing in

Terminology

• Pricing Plans settings: Site-level settings that apply to every pricing plan on the site. The plans themselves are managed with the Plans API.
• Taxable address: The address whose jurisdiction determines the tax applied to a plan purchase, either the buyer's billing address or the site owner's business address.
• Guest checkout: A plan purchase made by a site visitor who isn't signed in as a site member.

See also

• Plans: Creates and manages the plans themselves, including pricing and billing terms. The settings in this API apply across all of those plans.
• Site Properties: Holds the business address used when taxableAddress is BUSINESS. This API exposes the choice between addresses, not the addresses themselves.