Filter
Purchase options allow you to sell a single product in multiple ways, with different pricing and fulfillment settings. The default is a one-time purchase. Currently, you can also offer subscriptions—with more options like preorders and try-before-you-buy coming soon.
This is the most traditional way to sell—the full price is paid at checkout and you fulfill the product once. One-time pricing allows for setting the product's list price as well as defining a sale_price. The sale price can be enabled and disabled with the toggle—enabling will designate the product is on sale and the product's sale price will be reflected in your storefront.
In addition to the base list price and sale price, One-time pricing also supports additional price rules. These can be added to accommodate use cases such as:
- Providing different prices per customer group
- Specifying prices for a set maximum or minimum quantity of items purchased
Fields
Options that allow for variations of the base product. If the option is part of a variant or required=true, an option value must be set for the product to be added to a cart.
Unique identifier for the object.
Human-friendly name of the option.
Some brief hint text to help the user understand this option.
Type of user input to display for this option in a storefront. Can be text, textarea, select, multi_select, file, or multi_file. select is ideal for dropdown or radio selectors, and multi_select is ideal for checkboxes. A maximum of 10 files can be uploaded by the user, and there are no restrictions on file type.
Specifies another option ID that affects visibility of this option. The option will only appear when one of the parent_value_ids is selected.
IDs of parent option values that will make the option appear if selected.
Extra price for the option, added to the product's price/sale_price. If the option is part of a variant, the variant's price/sale_price will override this value.
Indicates whether the option requires a value when the product is added to a cart.
Indicates whether the option specifies the billing interval of a subscription plan.
List of possible values for this option.
Unique identifier for the object.
Human-friendly name of the option value.
A brief description of the option value, intended for displaying to customers.
Extra price added to the product's price/sale_price if the option value is selected. Overrides option price.
Extra weight added to the product's shipment_weight if the option value is selected. The unit should match the store's default as configured in general settings.
When product type=subscription, this is the billing interval used when this option value is selected. Can be monthly, yearly, weekly, or daily.
When product type=subscription, this number multiplies subscription_interval to determine the billing frequency when this option is selected. For example, to make a subscription bill every two weeks, set subscription_interval=weekly and subscription_interval_count=2.
When product type=subscription, refers to a number of days offered as a trial before an invoice is issued.
Unique identifier for the attribute.
Description for the product options.
Indicates the options are active.
Indicates there are multiple selections for options.
Indicates the option is a variant.
Indicates whether the product is on sale. If true, the sale_price will be used by default when the product is added to a cart.
Sale price used to override list price when sale=true.
If specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package.
Configuration of one or more purchase options for the product. Can be standard for one-time purchases or subscription for a subscription plan. Products can support both purchase options simultaneously.
Designates purchase option as a one-time purchase.
ID of the purchase option.
The name of the purchase option.
A long-form description of the product. May contain HTML or other markup languages.
Whether the product option is available for customers to purchase. Inactive products will not be returned in the Storefront API.
List price used when sale=false or sale_price is not defined.
Indicates whether the product option is on sale. If true, the sale_price will be used by default when the product is added to a cart.
Sale price used by default when sale=true, overriding price. Overrides product sale price.
Price rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Array of account groups that are eligible to access the purchase option within the storefront.
Designates purchase option as a subscription plan.
ID of the subscription plan purchase option.
Name of the subscription plan purchase option.
A long-form description of the purchase option. May contain HTML or other markup languages.
Whether the purchase option is available for customers to purchase. Inactive products will not be returned in the Storefront API.
Array of account_group names for which the purchase option is available.
ID of the purchase option subscription plan.
Name of the subscription plan.
A long-form description of the subscription plan. May contain HTML or other markup languages.
Whether the subscription plan is available for customers to purchase. Inactive products will not be returned in the Frontend API.
List price used when sale=false or sale_price is not defined.
Price rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Subscription plan billing interval. Can be daily, weekly, monthly, or yearly.
Multiplier for billing interval. For example, to make the billing cycle once every two weeks, set interval=weekly and interval_count=2.
Specifies a limit to the number of billing cycles for the subscription plan. For example, "limit"=10 would stop billing the customer after the tenth billing cycle.
Unique identifier for the product.
Human-friendly name of the product.
Whether the product is available for customers to purchase. Inactive products will not be returned in the Frontend API.
An object containing custom attribute key/value pairs. See for more details.
Indicates whether the product is a bundle of other products.
List of products sold as a bundle. Applicable only when bundle=true.
Unique identifier for the bundle item.
ID of the bundled product.
Expandable link to the bundled product.
Quantity of the bundled product. Defaults to 1.
ID of the bundled variant, if applicable.
Expandable link to the bundled product variant, if applicable.
Expandable link to the primary category.
Primary category, commonly used as a navigation anchor.
Expandable link to all related product categories.
Index of categories used for fast lookup operations.
List of related product category IDs.
Index of category IDs and their respective sort positions.
Cost of goods (COGS) used to calculate gross margins.
List of products to display as cross-sells on a shopping cart page.
Unique identifier for the cross-sell object.
ID of the cross-sell product.
Expandable link to the cross-sell product.
Type of discount to apply, either fixed or percent.
Discount to apply as a fixed amount. Applicable only when discount_type=fixed.
Discount to apply as a percentage. Applicable only when discount_type=percent.
Three-letter ISO currency code in uppercase. Defaults to your store's base currency.
Indicates whether the product has custom options enabled.
Date and time the product was created.
Date and time the product was last updated.
Method of fulfillment automatically assigned based on type:
- shipment means the product will be physically shipped to a customer.
- subscription means the product will be fulfilled as a subscription when an order is placed. giftcard delivery means the product will be fulfilled as a gift card when an order is placed.
- null means the product will not be fulfilled by one of the above methods.
Note: A bundle has its child products fulfilled individually; each product in the bundle must have its own fulfillment method.
A long-form description of the product. May contain HTML or other markup languages.
List of images depicting the bundle.
Unique identifier for the image.
A brief description of the image, intended for display as a caption or alt text.
An object representing the image's source file.
Unique identifier for the file.
Optional file name.
A reference to the raw file data.
MIME content type of the file.
Date the file was uploaded.
Image height in pixels, if applicable.
Size of the file in bytes.
An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
A public URL to reference the file. Updated automatically if file content changes.
Image width in pixels, if applicable.
Page title used to override product name in storefronts.
Page keywords used for search engine optimization purposes.
Page description used for search engine optimization purposes.
List price used when sale=false or sale_price is not defined.
Price rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Product dimensions when packed for shipping. Typically used by third-party carriers in box packing algorithms to optimize shipping costs.
Length of the product in unit.
Width of the product in unit.
Height of the product in unit.
Either in(inches) or cm(centimeters).
ID of location from /settings/shipping/locations. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used.
Product shipping price rules to override default shipping rules.
Shipping service required for this rule to apply.
Customer group required for this rule to apply.
Shipping country required for this rule to apply.
Fixed amount to add when rule is applied. Only applicable when fee_type=fixed.
Percentage of the shipping price to add when rule is applied. Only applicable when fee_type=percent.
Type of fee to apply in addition to price, either fixed or percent.
Maximum package quantity when rule is applied.
Shipping price when rule is applied.
Shipping state required for this rule to apply.
Maximum order subtotal for this rule to apply.
Minimum order subtotal for this rule to apply.
Maximum order item weight for this rule to apply.
Minimum order item weight for this rule to apply.
Shipping zip/postal code required for this rule to apply.
If specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg—depending on the store's default weight unit.
The default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly, or daily.
Multiplier when combined with subscription_interval. For example, to make a subscription bill every two weeks, set subscription_interval=weekly and subscription_interval_count=2.
Number of days offered as a free trial before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued.
Stock keeping unit (SKU) used to track inventory in a warehouse.
Lowercase, hyphenated identifier typically used in URLs. When creating a product, a slug will be generated automatically from the name. Maximum length of 1,000 characters.
Expandable list of stock adjustments for the product.
Minimum quantity of the product that can be sold at once.
Specifies a quantify multiple the product must be sold in.
Indicates whether the product has variant generation enabled.
Indicates whether the product has stock tracking enabled.
Quantity of the product currently in stock (including all variants), based on the sum of the stock entries.
String indicating the product's stock status for the purpose of ordering. When stock_purchasable=true, an order can be placed for this product regardless of current stock status. Otherwise an order submission will be blocked unless stock status is available, preorder, or backorder.
Implies the ordering and fulfillment options available for the product. Can be standard, subscription, bundle, or giftcard. A standard product is a physical item that will be shipped to a customer.
List of products to display as up-sells on a product detail page.
Unique identifier for the up-sell.
ID of the up-sell product.
Expandable link to the up-sell product.
Expandable list of variants representing unique variations of the product. Each variant is a combination of one or more options. For example, Size and Color.
Swell can handle subscriptions for physical and virtual products, including different billing and fulfillment schedules.
For virtual subscriptions, the customer is billed on a regular basis according to the plan they choose. An order is generated for the initial purchase, and invoices for subsequent intervals.
For physical subscriptions, invoices are generated according to the billing schedule, and orders according to the fulfillment schedule. This ensures that your operations team can ensure items are fulfilled in a timely manner.
Enabling the subscription pricing allows for the creation of subscription plans. Each subscription plan has its own interval, price, and also supports a trial period. Specifying the trial period allows for a customer to try your product subscription for the duration—billing cycles will begin once the trial period ends.
Fields
Configuration of one or more purchase options for the product. Can be standard for one-time purchases or subscription for a subscription plan. Products can support both purchase options simultaneously.
Designates purchase option as a one-time purchase.
ID of the purchase option.
The name of the purchase option.
A long-form description of the product. May contain HTML or other markup languages.
Whether the product option is available for customers to purchase. Inactive products will not be returned in the Storefront API.
List price used when sale=false or sale_price is not defined.
Indicates whether the product option is on sale. If true, the sale_price will be used by default when the product is added to a cart.
Sale price used by default when sale=true, overriding price. Overrides product sale price.
Price rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Array of account groups that are eligible to access the purchase option within the storefront.
Designates purchase option as a subscription plan.
ID of the subscription plan purchase option.
Name of the subscription plan purchase option.
A long-form description of the purchase option. May contain HTML or other markup languages.
Whether the purchase option is available for customers to purchase. Inactive products will not be returned in the Storefront API.
Array of account_group names for which the purchase option is available.
ID of the purchase option subscription plan.
Name of the subscription plan.
A long-form description of the subscription plan. May contain HTML or other markup languages.
Whether the subscription plan is available for customers to purchase. Inactive products will not be returned in the Frontend API.
List price used when sale=false or sale_price is not defined.
Price rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Subscription plan billing interval. Can be daily, weekly, monthly, or yearly.
Multiplier for billing interval. For example, to make the billing cycle once every two weeks, set interval=weekly and interval_count=2.
Specifies a limit to the number of billing cycles for the subscription plan. For example, "limit"=10 would stop billing the customer after the tenth billing cycle.
Unique identifier for the product.
Human-friendly name of the product.
Whether the product is available for customers to purchase. Inactive products will not be returned in the Frontend API.
An object containing custom attribute key/value pairs. See for more details.
Indicates whether the product is a bundle of other products.
List of products sold as a bundle. Applicable only when bundle=true.
Unique identifier for the bundle item.
ID of the bundled product.
Expandable link to the bundled product.
Quantity of the bundled product. Defaults to 1.
ID of the bundled variant, if applicable.
Expandable link to the bundled product variant, if applicable.
Expandable link to the primary category.
Primary category, commonly used as a navigation anchor.
Expandable link to all related product categories.
Index of categories used for fast lookup operations.
List of related product category IDs.
Index of category IDs and their respective sort positions.
Cost of goods (COGS) used to calculate gross margins.
List of products to display as cross-sells on a shopping cart page.
Unique identifier for the cross-sell object.
ID of the cross-sell product.
Expandable link to the cross-sell product.
Type of discount to apply, either fixed or percent.
Discount to apply as a fixed amount. Applicable only when discount_type=fixed.
Discount to apply as a percentage. Applicable only when discount_type=percent.
Three-letter ISO currency code in uppercase. Defaults to your store's base currency.
Indicates whether the product has custom options enabled.
Date and time the product was created.
Date and time the product was last updated.
Method of fulfillment automatically assigned based on type:
- shipment means the product will be physically shipped to a customer.
- subscription means the product will be fulfilled as a subscription when an order is placed. giftcard delivery means the product will be fulfilled as a gift card when an order is placed.
- null means the product will not be fulfilled by one of the above methods.
Note: A bundle has its child products fulfilled individually; each product in the bundle must have its own fulfillment method.
A long-form description of the product. May contain HTML or other markup languages.
List of images depicting the bundle.
Unique identifier for the image.
A brief description of the image, intended for display as a caption or alt text.
An object representing the image's source file.
Unique identifier for the file.
Optional file name.
A reference to the raw file data.
MIME content type of the file.
Date the file was uploaded.
Image height in pixels, if applicable.
Size of the file in bytes.
An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
A public URL to reference the file. Updated automatically if file content changes.
Image width in pixels, if applicable.
Page title used to override product name in storefronts.
Page keywords used for search engine optimization purposes.
Page description used for search engine optimization purposes.
Options that allow for variations of the base product. If the option is part of a variant or required=true, an option value must be set for the product to be added to a cart.
Unique identifier for the object.
Human-friendly name of the option.
Some brief hint text to help the user understand this option.
Type of user input to display for this option in a storefront. Can be text, textarea, select, multi_select, file, or multi_file. select is ideal for dropdown or radio selectors, and multi_select is ideal for checkboxes. A maximum of 10 files can be uploaded by the user, and there are no restrictions on file type.
Specifies another option ID that affects visibility of this option. The option will only appear when one of the parent_value_ids is selected.
IDs of parent option values that will make the option appear if selected.
Extra price for the option, added to the product's price/sale_price. If the option is part of a variant, the variant's price/sale_price will override this value.
Indicates whether the option requires a value when the product is added to a cart.
Indicates whether the option specifies the billing interval of a subscription plan.
List of possible values for this option.
Unique identifier for the object.
Human-friendly name of the option value.
A brief description of the option value, intended for displaying to customers.
Extra price added to the product's price/sale_price if the option value is selected. Overrides option price.
Extra weight added to the product's shipment_weight if the option value is selected. The unit should match the store's default as configured in general settings.
When product type=subscription, this is the billing interval used when this option value is selected. Can be monthly, yearly, weekly, or daily.
When product type=subscription, this number multiplies subscription_interval to determine the billing frequency when this option is selected. For example, to make a subscription bill every two weeks, set subscription_interval=weekly and subscription_interval_count=2.
When product type=subscription, refers to a number of days offered as a trial before an invoice is issued.
Unique identifier for the attribute.
Description for the product options.
Indicates the options are active.
Indicates there are multiple selections for options.
Indicates the option is a variant.
List price used when sale=false or sale_price is not defined.
Price rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Indicates whether the product is on sale. If true, the sale_price will be used by default when the product is added to a cart.
Sale price used to override list price when sale=true.
Product dimensions when packed for shipping. Typically used by third-party carriers in box packing algorithms to optimize shipping costs.
Length of the product in unit.
Width of the product in unit.
Height of the product in unit.
Either in(inches) or cm(centimeters).
ID of location from /settings/shipping/locations. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used.
If specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package.
Product shipping price rules to override default shipping rules.
Shipping service required for this rule to apply.
Customer group required for this rule to apply.
Shipping country required for this rule to apply.
Fixed amount to add when rule is applied. Only applicable when fee_type=fixed.
Percentage of the shipping price to add when rule is applied. Only applicable when fee_type=percent.
Type of fee to apply in addition to price, either fixed or percent.
Maximum package quantity when rule is applied.
Shipping price when rule is applied.
Shipping state required for this rule to apply.
Maximum order subtotal for this rule to apply.
Minimum order subtotal for this rule to apply.
Maximum order item weight for this rule to apply.
Minimum order item weight for this rule to apply.
Shipping zip/postal code required for this rule to apply.
If specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg—depending on the store's default weight unit.
The default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly, or daily.
Multiplier when combined with subscription_interval. For example, to make a subscription bill every two weeks, set subscription_interval=weekly and subscription_interval_count=2.
Number of days offered as a free trial before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued.
Stock keeping unit (SKU) used to track inventory in a warehouse.
Lowercase, hyphenated identifier typically used in URLs. When creating a product, a slug will be generated automatically from the name. Maximum length of 1,000 characters.
Expandable list of stock adjustments for the product.
Minimum quantity of the product that can be sold at once.
Specifies a quantify multiple the product must be sold in.
Indicates whether the product has variant generation enabled.
Indicates whether the product has stock tracking enabled.
Quantity of the product currently in stock (including all variants), based on the sum of the stock entries.
String indicating the product's stock status for the purpose of ordering. When stock_purchasable=true, an order can be placed for this product regardless of current stock status. Otherwise an order submission will be blocked unless stock status is available, preorder, or backorder.
Implies the ordering and fulfillment options available for the product. Can be standard, subscription, bundle, or giftcard. A standard product is a physical item that will be shipped to a customer.
List of products to display as up-sells on a product detail page.
Unique identifier for the up-sell.
ID of the up-sell product.
Expandable link to the up-sell product.
Expandable list of variants representing unique variations of the product. Each variant is a combination of one or more options. For example, Size and Color.
If you have been using Swell and were selling subscriptions with the old configuration for subscriptions involving the use of bundle items, you will encounter a message both on the Storefront tab and on the particular product that features the legacy subscription setup.
In order to upgrade the product subscription, there are two areas that will need to be updated: your product(s) and your Storefront.
You can update your subscription plans through the API console in the dashboard directly with the following PUT request—you can also write a script to automate the process.
PUT /products/<id> { type: 'physical' or 'digital' }Specify the request with the type set to 'physical' for a subscription plan that has physical products, or 'digital' if the subscription has digital products.
This requires the affected product's id. This can be obtained by navigating to the product, clicking the </> icon on the top right to view the product in the console, and copying the id found at the end of the GET request (after /product/).
Dev tools will need to be enabled for the </> icon to be visible
This id can then be used to enter the above PUT request within the Console. The API console is found under Developer > Console in the dashboard nav.
To create the request:
- Select PUT
- Choose /products under Collection
- Paste the product id in the URI field
- Enter type: 'digital' or 'physical' in the Body based on the product
- Press Run to make the change to the product.
Lastly, go to the product page and press Save product to finalize the update. Your product will now be configured with the updated Subscription purchase option.
If you do not save the product from the product page, the change will not take effect.
In addition to updating your product purchase options, your storefront needs to be updated to support the new purchase options. Changes to the product without also adjusting the storefront can lead to issues when trying to purchase a product.
If you are using a Swell theme, you can remedy this by updating to the latest build of your theme. If you need assistance updating your theme, see our guide for updating your Swell theme with git.
For custom storefronts, a solution can be implemented via Frontend API. See an example.
Once changes have been made to both the product and the storefront, you should no longer see the error message display, and your storefront will be fully compatible with your new product subscription options.