Product Variants, Pricing, and Subscription Configuration

The Prices & Variants tab on the product edit page is where you define every purchasable option for a product — from size and color attributes to subscription billing IDs, gift wrapping fees, and event session details. Each variant carries its own pricing, inventory, tax settings, and optional payment processor IDs for Stripe and Paddle subscriptions.

Variant Management

The Prices & Variants section lives on the product edit page. Each product can have one or more variants representing different sizes, colors, editions, or event sessions.

Inline Variant Attributes Builder

Add Attribute Key–Value Pairs

Use the key-value builder to define attributes for this variant. For example:

Color → Blue
Size → XL

Auto-Compiled JSON

As you add pairs, the builder auto-compiles the entries into a JSON structure in the background.

Raw JSON Mode

Advanced users can switch to the raw JSON textarea to paste or edit the compiled JSON directly.

Duplicate a Variant

The Duplicate Variant action clones all of the following from the source variant into a new record:

Attributes & Prices

All pricing fields and attribute key-value pairs

Custom S3 Credentials

Per-variant S3 bucket credentials if configured

Inventory Records

Stock levels, warehouse levels, reserved stock, and location assignments

Processor Price IDs

All Paddle and Stripe subscription price IDs

Image Sets

Full image gallery (thumbnail, main, zoom paths)

The duplicate is assigned a guaranteed unique SKU automatically — no manual entry needed.

UI Behavior

Auto-Close Variant Modal: after creating or editing a variant the overlay closes automatically, returning you to the variant list.
Edit & Inventory Scroll Anchor: clicking the “Edit & Inventory” button on any variant row scrolls the page directly to #section-variants.

Pricing Fields

Field	Description
`public_price`	Standard retail price shown to all customers
`wholesale_price`	Discounted price for wholesale customers (`role_id = 2`)
`sale_price`	Sale / promotional price — the original price renders with a strikethrough on the storefront
`variant_fee`	Additional selection fee added to the unit price when this variant is chosen (e.g. `+$5.00` for size XXL)
`wholesale_variant_fee`	Variant fee charged to wholesale-tier customers

Leave sale_price blank to hide the strikethrough on the storefront. A value of 0 is treated as a valid sale price (free), not as “no sale.”

Tax Control (`charge_tax`)

Tax is configurable at the individual variant level.

Toggle Behavior
Tax Calculation Logic

State	Label	Badge in Variant List
ON (default)	Sales Tax / VAT — Taxable	🟢 Green dot — Taxable
OFF	Sales Tax / VAT — Exempt	⚫ Grey dot — Exempt

The toggle appears as a green/grey pill switch inside both the variant create and edit forms.

When charge_tax is toggled OFF for a variant, that variant’s line-item price is fully excluded from tax calculations.The OR Rule that governs taxability at the line-item level:

item_taxable = 1
  IF (variant.charge_tax = 1)
  OR (any product_field.charge_tax = 1 for this product)

This means if any Product Customization Field on the same product has charge_tax = 1, the entire line item remains taxable even if the variant itself is set to Exempt.

Payment Processor IDs (Subscription Billing)

The Payment Processor IDs panel is collapsible inside the variant create/edit form. A “Configured” badge appears on the collapsed header whenever any field in this section has a value.

Paddle

Field	Description	Example Value
`paddle_sandbox_price_id`	Paddle Price ID for sandbox / test mode	`pri_sandbox_xxxxxxxxx`
`paddle_live_price_id`	Paddle Price ID for live / production mode	`pri_xxxxxxxxx`

Stripe

Field	Description	Example Value
`stripe_sandbox_price_id`	Stripe Test Price ID	`price_test_xxxxxxxxx`
`stripe_live_price_id`	Stripe Live Price ID	`price_xxxxxxxxx`
`create_new_stripe_product`	Toggle — when ON, a new Stripe Product and recurring Price are created automatically at checkout	—
`stripe_billing_interval`	Billing frequency	`month`, `year`, `week`
`stripe_trial_enabled`	Toggle — enables a free trial period for this subscription	—
`stripe_trial_days`	Number of free trial days (only active when `stripe_trial_enabled = 1`)	`14`

create_new_stripe_product is useful for products that don’t yet have a corresponding Stripe catalog entry. Leave it OFF if you are mapping to an existing Stripe Price object.

Download Settings (Variant Level)

For digital / downloadable products, each variant carries its own download restrictions:

Field	Default	Description
Download Expiration Date	1 year from today	Date after which download links expire and can no longer be accessed
Max Downloads	100	Maximum number of download attempts permitted per order

Once a download link expires or the max-download count is reached, the customer will see an error on the download page. Adjust these defaults before publishing high-volume digital products.

Gift Wrapping / Personalization (Variant Level)

Field	Description
Enable Personalization	Toggle to activate personalization for this specific variant
Personalization Label	Customer-facing label displayed above the text input (e.g. `"Add Gift Message"`, `"Engraving Text"`)
Personalization Fee	Optional fee added to the unit price for this service (`+$0` for free)
Wholesale Personalization Fee	Separate personalization fee applied to wholesale accounts
Placeholder / Instructions	Helper text shown inside the customer’s text input field

Event Details (Variant Level)

Toggle “Mark as Event / Calendar Item” (rendered as a violet pill-switch) to enable event mode for this variant.

Modeling pattern: the parent Product represents the event series (e.g. “Summer Pottery Workshop”), and each Variant represents an individual session or time slot. Customers purchase a specific variant to register for that session.

Field	Required	Description
Event Label	✅ Yes	Primary text shown on the calendar tile
Alternate / Tooltip Label	No	Secondary label used for tooltips or compact views
Event Start Date & Time	✅ Yes	`datetime-local` picker — required for calendar rendering
Event End Date & Time	No	Optional session end time
Calendar Colour	No	Hex color code for the badge/tile (default: `#4f46e5`)
Sort Order	No	Float weight for calendar display ordering
Show Date on Front-End	No	Checkbox — controls whether the date is visible on the public calendar
Location / Venue / URL	No	Physical address or online meeting link (e.g. Zoom URL)
Event Description	No	Rich text area for detailed session notes, agenda, or instructions

Product Customization Fields Panel

The Product Customization Fields panel is a dynamic form builder for adding custom checkout input fields to a product.

Supported Field Types

Free-text input
Single-select dropdown
Radio group
Checkbox (boolean)
Multi-select

Per-Field Pricing & Tax

Each custom field supports:

Setting	Description
Retail price surcharge	Extra amount added to the unit price for retail customers
Wholesale price surcharge	Extra amount added for wholesale-tier customers
Tax Price Modifier (`charge_tax`)	Toggle (default ON) — controls whether this field’s surcharge is included in tax calculations

Advanced Settings Panel

Setting	Description
Max 1 per order (`max_qty`)	Forces the quantity to 1 for this product; disables all quantity selectors in cart and on the product page
Redirect to Checkout (`checkout_redirect`)	Bypasses the cart on add-to-cart and sends the customer directly to checkout
Standalone Purchase (`standalone_purchase`)	Blocks adding any other items to the cart while this product is present
Use Dependent Selectors (`dependent_variants`)	Enables a progressive Color → Size drill-down — the second selector only appears after the first is chosen
Hide Inventory Levels (`hide_inventory_levels`)	Hides the “X in stock” indicator on the product page regardless of actual stock
★ Featured Item	Marks the product as featured — required for it to appear in the `[plugin:featured-items]` shortcode output
Product Page Layout Option	Select from 5 available storefront layout templates (see Storefront Layout docs)
Post-Order Completion Redirect	Custom URL or `[page:ID]` shortcode — customer is redirected here after a successful purchase

Getting Started

Storefront

Admin: Products

Admin: Orders & Sales

Admin: CMS

Payments & Subscriptions

Plugins & Extensions

Support & Helpdesk

Configuration

Product Variants, Pricing, and Subscription Configuration

Variant Management

Inline Variant Attributes Builder

Duplicate a Variant

Attributes & Prices

Custom S3 Credentials

Inventory Records

Processor Price IDs

Image Sets

UI Behavior

Pricing Fields

Tax Control (`charge_tax`)

Payment Processor IDs (Subscription Billing)

Paddle

Stripe

Download Settings (Variant Level)

Gift Wrapping / Personalization (Variant Level)

Event Details (Variant Level)

Product Customization Fields Panel

Supported Field Types

Per-Field Pricing & Tax

Advanced Settings Panel

​Variant Management

​Inline Variant Attributes Builder

​Duplicate a Variant

Attributes & Prices

Custom S3 Credentials

Inventory Records

Processor Price IDs

Image Sets

​UI Behavior

​Pricing Fields

​Tax Control (charge_tax)

​Payment Processor IDs (Subscription Billing)

​Paddle

​Stripe

​Download Settings (Variant Level)

​Gift Wrapping / Personalization (Variant Level)

​Event Details (Variant Level)

​Product Customization Fields Panel

​Supported Field Types

​Per-Field Pricing & Tax

​Advanced Settings Panel

Variant Management

Inline Variant Attributes Builder

Duplicate a Variant

UI Behavior

Pricing Fields

Tax Control (`charge_tax`)

Payment Processor IDs (Subscription Billing)

Paddle

Stripe

Download Settings (Variant Level)

Gift Wrapping / Personalization (Variant Level)

Event Details (Variant Level)

Product Customization Fields Panel

Supported Field Types

Per-Field Pricing & Tax

Advanced Settings Panel