Guides
Swell products have four basic product types: physical, virtual, bundle, and gift card. Each type has a distinct way of operating within the API. Each type has unique dashboard UI fields and setting configurations. You can use any of the default product types to build your own custom product types.
These are tangible products that exist in the real world. They either need to be shipped to the customer or picked up at a store location. Physical products have shipping details like weight and package dimensions. They can have inventory tracking enabled if desired.
Set delivery="shipment" to create a physical product.
Digital products exist only in the virtual realm and are either delivered digitally or used for billing services. It's up to you to deliver that product or service to the customer. Virtual products have no shipping details, but they can have inventory tracking enabled.
Set virtual=true to create a virtual product.
Bundle products are made up of multiple products from your catalog. These are ideal for selling kits or combinations of products together. Bundle products appear in carts as a single product and can have inventory tracking for both the bundle itself and the products contained within it. Bundles can be any combination of physical, virtual, and gift card product types. Each product within a bundle needs its own fulfillment method
Set bundle=true to create a bundle product.
Gift card products work like customer credit, which can be applied to later orders. These products have enumerated denominations chosen by the purchaser. Gift cards can either be delivered digitally or physically, and they do support inventory tracking.
Set delivery="giftcard" to create a gift card product.
Gift cards act as a payment method and are stored in a customer's account as credit. This credit can be applied to purchases directly from their account balance during checkout. They do not operate like promotions and will not affect the order total.
You can use any of these product types as the basis for creating a custom type. Custom product types can group together products with similar characteristics. You can define the custom type's attributes, categories, options, variant settings, and more—allowing you to streamline the process for creating new products and ensuring consistency across product families within your catalog.
The only required field when creating a new product is name. Swell automatically creates a URL-friendly slug based on the product's name. You can substitute this slug in place of the id when fetching the product in an API call.
Product attributes are a first-class feature in Swell, and they support a variety of data types like text, image, file, and number. When creating a product, you can assign existing attributes or define new ones. Attributes can be used as filters when fetching products and can be further specified as to whether they are displayed on the product page.
Use categories to relate and organize products together. Product categories can also be nested within one another, meaning a category can contain several sub-categories. This allows for additional organizational flexibility.
Designate the product sku (stock keeping unit) for inventory tracking purposes.
Product options define choices for a product that the customer chooses from. Some common examples of product options are size and color. Swell offers a variety of product option types including select, toggle, and text.
Fields
options
array of objectOptions 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.
id
objectIdautoUnique identifier for the object.
name
stringrequiredHuman-friendly name of the option.
input_hint
stringSome brief hint text to help the user understand this option.
input_type
enumType 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.
parent_id
objectIdSpecifies another option ID that affects visibility of this option. The option will only appear when one of the parent_value_ids is selected.
parent_value_ids
array of child_scalarIDs of parent option values that will make the option appear if selected.
price
currencyExtra 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.
required
booleanIndicates whether the option requires a value when the product is added to a cart.
subscription
booleanIndicates whether the option specifies the billing interval of a subscription plan.
values
array of objectList of possible values for this option.
id
objectIdautoUnique identifier for the object.
name
stringrequiredHuman-friendly name of the option value.
color
stringName of the product color.
description
stringA brief description of the option value, intended for displaying to customers.
price
currencyExtra price added to the product's price/sale_price if the option value is selected. Overrides option price.
shipment_weight
floatExtra 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.
subscription_interval
enumWhen product type=subscription, this is the billing interval used when this option value is selected. Can be monthly, yearly, weekly, or daily.
Possible enum values:
subscription_interval_count
intWhen 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.
subscription_trial_days
intWhen product type=subscription, refers to a number of days offered as a trial before an invoice is issued.
image
objectImage depicting the product.
image.id
objectIdUnique identifier for the object.
image.data
filedataA reference to the raw file data.
image.date_uploaded
dateDate the file was uploaded.
image.length
intSize of the file in bytes.
image.md5
stringAn MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
image.filename
stringOptional file name.
image.content_type
stringMIME content type of the file.
image.metadata
objectArbitrary data
image.private
booleanimage.url
stringimage.width
intimage.height
intimages
array of objectid
objectIdautocaption
stringfile
objectfile.id
objectIdfile.date_uploaded
datefile.length
intfile.md5
stringfile.filename
stringfile.content_type
stringfile.metadata
objectfile.data
filedatafile.private
booleanfile.url
stringfile.width
intfile.height
intattribute_id
stringUnique identifier for the attribute.
description
stringDescription for the product options.
active
booleanIndicates the options are active.
input_multi
booleanIndicates there are multiple selections for options.
variant
booleanIndicates the option is a variant.
id
objectIdUnique identifier for the product.
name
stringrequiredHuman-friendly name of the product.
active
booleanIndicates whether the product is active and available in the storefront.
purchase_options
objectConfiguration 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.
purchase_options.standard
objectDesignates purchase option as a one-time purchase.
standard.id
objectIdID of the purchase option.
standard.name
stringrequiredThe name of the purchase option.
standard.description
stringA long-form description of the product. May contain HTML or other markup languages.
standard.active
booleanIndicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
standard.price
currencyList price used when sale=false or sale_price is not defined.
standard.sale
booleanIndicates 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.
standard.sale_price
currencySale price used by default when sale=true, overriding price. Overrides product sale price.
standard.prices
array of objectPrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
.price
currencyrequiredPrice applied when conditions are met.
.account_group
stringCustomer account group as a condition to apply price.
.quantity_max
intMaximum quantity as a condition to apply price.
.quantity_min
intMinimum quantity as a condition to apply price.
standard.account_groups
array of stringArray of account groups that are eligible to access the purchase option within the storefront.
purchase_options.subscription
objectDesignates purchase option for a subscription plan.
subscription.id
objectIdautoID of the subscription plan purchase option.
subscription.name
stringrequiredName of the subscription plan purchase option.
subscription.description
stringA long-form description of the purchase option. May contain HTML or other markup languages.
subscription.active
booleanIndicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
subscription.account_groups
array of stringArray of account_group names for which the purchase option is available.
subscription.plans
array of plansArray defining subscription plans and their respective configurations.
plans.id
objectIdID of the purchase option subscription plan.
plans.name
stringrequiredName of the subscription plan.
plans.description
stringA long-form description of the subscription plan. May contain HTML or other markup languages.
plans.active
booleanIndicates whether the subscription plan is available for customers to purchase. Inactive products will not be returned on the Frontend.
plans.price
currencyList price used when sale=false or sale_price is not defined.
plans.prices
array of objectPrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
.price
currencyrequiredPrice applied when conditions are met.
.account_group
stringCustomer account group as a condition to apply price.
.quantity_max
intMaximum quantity as a condition to apply price.
.quantity_min
intMinimum quantity as a condition to apply price.
plans.billing_schedule
objectrequiredDetermines the billing schedule for the subscription plan.
billing_schedule.interval
enumSubscription plan billing interval. Can be daily, weekly, monthly, or yearly.
Possible enum values:
billing_schedule.interval_count
intrequiredMultiplier for billing interval. For example, to make the billing cycle once every two weeks, set interval=weekly and interval_count=2.
billing_schedule.limit
intSpecifies 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.
billing_schedule.trial_days
intNumber of days offered as a free trial on the subscription plan before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued.
attributes
objectAn object containing custom attribute key/value pairs.
bundle
booleanIndicates whether the product is a bundle of other products.
bundle_items
array of objectList of products sold as a bundle. Applicable only when bundle=true.
id
objectIdautoUnique identifier for the bundle item.
product_id
objectIdrequiredID of the bundled product.
product
ProductExpandable link to the bundled product.
quantity
intQuantity of the bundled product. Defaults to 1.
variant_id
objectIdID of the bundled variant, if applicable.
variant
Product variantExpandable link to the bundled product variant, if applicable.
product_name
stringThis field is a copy of the item's product.name.
category
CategoryExpandable link to the primary category.
category_id
objectIdPrimary category, commonly used as a navigation anchor.
categories
CategoryExpandable link to all related product categories.
category_index
objectIndex of categories used for fast lookup operations.
category_index.id
array of child_scalarList of related product category IDs.
category_index.sort
objectIndex of category IDs and their respective sort positions.
code
stringUnique code to identify the gift card product.
cost
currencyCost of goods (COGS) used to calculate gross margins.
cross_sells
array of objectList of products to display as cross-sells on a shopping cart page.
id
objectIdautoUnique identifier for the cross-sell object.
product_id
objectIdrequiredID of the cross-sell product.
product
ProductExpandable link to the cross-sell product.
discount_type
enumType of discount to apply, either fixed or percent.
discount_amount
currencyDiscount to apply as a fixed amount. Applicable only when discount_type=fixed.
discount_percent
floatDiscount to apply as a percentage. Applicable only when discount_type=percent.
currency
stringThree-letter ISO currency code in uppercase. Defaults to your store's base currency.
customizable
booleanIndicates whether the product has custom options enabled.
date_created
dateautoDate and time the product was created.
date_updated
dateautoDate and time the product was last updated.
delivery
enumautoMethod 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.
description
stringA long-form description of the product. May contain HTML or other markup languages.
discontinued
booleanIndicates whether the product has been discontinued.
images
array of objectList of images depicting the bundle.
id
objectIdautoUnique identifier for the image.
caption
stringA brief description of the image, intended for display as a caption or alt text.
file
objectAn object representing the image's source file.
file.id
objectIdUnique identifier for the file.
file.filename
stringOptional file name.
file.data
filedataA reference to the raw file data.
file.content_type
stringMIME content type of the file.
file.date_uploaded
dateDate the file was uploaded.
file.height
intImage height in pixels, if applicable.
file.length
intSize of the file in bytes.
file.metadata
objectA set of arbitrary data that is typically used to store custom values.
file.md5
stringAn MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
file.private
booleanIndicates whether the file is private.
file.url
stringA public URL to reference the file. Updated automatically if file content changes.
file.width
intImage width in pixels, if applicable.
meta_title
stringPage title used to override product name in storefronts.
meta_keywords
stringPage keywords used for search engine optimization purposes.
meta_description
stringPage description used for search engine optimization purposes.
orig_price
currencyReflects the non-sale price of the product
price
currencyList price used when sale=false or sale_price is not defined. This value is intended for use via the frontend. See the purchase_options array to manage a product's price.
prices
array of pricePrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
price.price
currencyrequiredPrice applied when conditions are met.
price.account_group
stringCustomer account group as a condition to apply price.
price.quantity_max
intMaximum quantity as a condition to apply price.
price.quantity_min
intMinimum quantity as a condition to apply price.
quantity_min
intMinimum quantity of the product that can be sold at once.
quantity_inc
intSpecifies a quantify multiple the product must be sold in.
related_product_ids
array of child_scalarArray of related product IDs.
sale
booleanIndicates 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
currencySale price used to override list price when sale=true.
shipment_dimensions
objectrequiredProduct dimensions when packed for shipping. Typically used by third-party carriers in box packing algorithms to optimize shipping costs.
shipment_dimensions.length
floatrequiredLength of the product in unit.
shipment_dimensions.width
floatrequiredWidth of the product in unit.
shipment_dimensions.height
floatrequiredHeight of the product in unit.
shipment_dimensions.unit
enumrequiredEither in(inches) or cm(centimeters).
shipment_location
stringID of location from /settings/shipping/locations. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used.
shipment_package_quantity
floatIf specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package.
shipment_prices
array of objectProduct shipping price rules to override default shipping rules.
service
stringrequiredShipping service required for this rule to apply.
account_group
stringCustomer group required for this rule to apply.
country
stringShipping country required for this rule to apply.
fee_amount
currencyFixed amount to add when rule is applied. Only applicable when fee_type=fixed.
fee_percent
floatPercentage of the shipping price to add when rule is applied. Only applicable when fee_type=percent.
fee_type
enumType of fee to apply in addition to price, either fixed or percent.
package_quantity
intMaximum package quantity when rule is applied.
price
currencyShipping price when rule is applied.
state
stringShipping state required for this rule to apply.
total_max
currencyMaximum order subtotal for this rule to apply.
total_min
currencyMinimum order subtotal for this rule to apply.
weight_max
floatMaximum order item weight for this rule to apply.
weight_min
floatMinimum order item weight for this rule to apply.
zip
stringShipping zip/postal code required for this rule to apply.
shipment_weight
floatIf specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg—depending on the store's default weight unit.
subscription_interval
enumThe default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly, or daily.
subscription_interval_count
intMultiplier when combined with subscription_interval. For example, to make a subscription bill every two weeks, set subscription_interval=weekly and subscription_interval_count=2.
subscription_trial_days
intNumber 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.
sku
stringrequiredStock keeping unit (SKU) used to track inventory in a warehouse.
slug
stringrequiredLowercase, 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.
stock
array of StockExpandable list of stock adjustments for the product.
stock_backorder
booleanIndicates whether the product can be backordered if out of stock.
stock_level
intQuantity of the product currently in stock (including all variants), based on the sum of the stock entries.
stock_preorder
booleanIndicates whether the product can be purchased as a preorder.
stock_purchasable
booleanIndicates whether the product's stock is purchasable.
stock_status
enumautoString 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.
stock_tracking
booleanIndicates whether the product has stock tracking enabled.
summary
stringA brief product summary.
tags
array of child_scalarArray of searchable tags to aid in search discoverability.
tax_class
stringIndicates the tax class for the product.
tax_code
stringProduct tax code for tracking with Avalara, TaxJar, etc.
type
stringImplies 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.
up_sells
array of objectList of products to display as up-sells on a product detail page.
id
objectIdautoUnique identifier for the up-sell.
product_id
objectIdrequiredID of the up-sell product.
product
ProductExpandable link to the up-sell product.
variable
booleanIndicates whether the product has variant generation enabled.
variants
array of VariantsExpandable list of variants representing unique variations of the product. Each variant is a combination of one or more options. For example, Size and Color.
virtual
booleanIndicates whether the product is virtual.
Product variants are an instance of a product that has a specific combination of options. Variants can have their own pricing, images, shipping properties, and inventory tracking. When variables=true, Swell automatically generates variants for products from all options that have variant=true. These entries are paginated, and there is no technical limit on the number of variants per product. Please be aware that high variant counts might affect performance. When creating product variant options, attributes of the same name will also be created if they do not already exist. This assists in filtering for the variant options within a UI that uses attributes as the filtering mechanism.
Fields
variants
array of VariantsExpandable list of variants representing unique variations of the product. Each variant is a combination of one or more options. For example, Size and Color.
id
objectIdUnique identifier for the product.
name
stringrequiredHuman-friendly name of the product.
active
booleanIndicates whether the product is active and available in the storefront.
purchase_options
objectConfiguration 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.
purchase_options.standard
objectDesignates purchase option as a one-time purchase.
standard.id
objectIdID of the purchase option.
standard.name
stringrequiredThe name of the purchase option.
standard.description
stringA long-form description of the product. May contain HTML or other markup languages.
standard.active
booleanIndicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
standard.price
currencyList price used when sale=false or sale_price is not defined.
standard.sale
booleanIndicates 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.
standard.sale_price
currencySale price used by default when sale=true, overriding price. Overrides product sale price.
standard.prices
array of objectPrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
.price
currencyrequiredPrice applied when conditions are met.
.account_group
stringCustomer account group as a condition to apply price.
.quantity_max
intMaximum quantity as a condition to apply price.
.quantity_min
intMinimum quantity as a condition to apply price.
standard.account_groups
array of stringArray of account groups that are eligible to access the purchase option within the storefront.
purchase_options.subscription
objectDesignates purchase option for a subscription plan.
subscription.id
objectIdautoID of the subscription plan purchase option.
subscription.name
stringrequiredName of the subscription plan purchase option.
subscription.description
stringA long-form description of the purchase option. May contain HTML or other markup languages.
subscription.active
booleanIndicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
subscription.account_groups
array of stringArray of account_group names for which the purchase option is available.
subscription.plans
array of plansArray defining subscription plans and their respective configurations.
plans.id
objectIdID of the purchase option subscription plan.
plans.name
stringrequiredName of the subscription plan.
plans.description
stringA long-form description of the subscription plan. May contain HTML or other markup languages.
plans.active
booleanIndicates whether the subscription plan is available for customers to purchase. Inactive products will not be returned on the Frontend.
plans.price
currencyList price used when sale=false or sale_price is not defined.
plans.prices
array of objectPrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
.price
currencyrequiredPrice applied when conditions are met.
.account_group
stringCustomer account group as a condition to apply price.
.quantity_max
intMaximum quantity as a condition to apply price.
.quantity_min
intMinimum quantity as a condition to apply price.
plans.billing_schedule
objectrequiredDetermines the billing schedule for the subscription plan.
billing_schedule.interval
enumSubscription plan billing interval. Can be daily, weekly, monthly, or yearly.
Possible enum values:
billing_schedule.interval_count
intrequiredMultiplier for billing interval. For example, to make the billing cycle once every two weeks, set interval=weekly and interval_count=2.
billing_schedule.limit
intSpecifies 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.
billing_schedule.trial_days
intNumber of days offered as a free trial on the subscription plan before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued.
attributes
objectAn object containing custom attribute key/value pairs.
bundle
booleanIndicates whether the product is a bundle of other products.
bundle_items
array of objectList of products sold as a bundle. Applicable only when bundle=true.
id
objectIdautoUnique identifier for the bundle item.
product_id
objectIdrequiredID of the bundled product.
product
ProductExpandable link to the bundled product.
quantity
intQuantity of the bundled product. Defaults to 1.
variant_id
objectIdID of the bundled variant, if applicable.
variant
Product variantExpandable link to the bundled product variant, if applicable.
product_name
stringThis field is a copy of the item's product.name.
category
CategoryExpandable link to the primary category.
category_id
objectIdPrimary category, commonly used as a navigation anchor.
categories
CategoryExpandable link to all related product categories.
category_index
objectIndex of categories used for fast lookup operations.
category_index.id
array of child_scalarList of related product category IDs.
category_index.sort
objectIndex of category IDs and their respective sort positions.
code
stringUnique code to identify the gift card product.
cost
currencyCost of goods (COGS) used to calculate gross margins.
cross_sells
array of objectList of products to display as cross-sells on a shopping cart page.
id
objectIdautoUnique identifier for the cross-sell object.
product_id
objectIdrequiredID of the cross-sell product.
product
ProductExpandable link to the cross-sell product.
discount_type
enumType of discount to apply, either fixed or percent.
discount_amount
currencyDiscount to apply as a fixed amount. Applicable only when discount_type=fixed.
discount_percent
floatDiscount to apply as a percentage. Applicable only when discount_type=percent.
currency
stringThree-letter ISO currency code in uppercase. Defaults to your store's base currency.
customizable
booleanIndicates whether the product has custom options enabled.
date_created
dateautoDate and time the product was created.
date_updated
dateautoDate and time the product was last updated.
delivery
enumautoMethod 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.
description
stringA long-form description of the product. May contain HTML or other markup languages.
discontinued
booleanIndicates whether the product has been discontinued.
images
array of objectList of images depicting the bundle.
id
objectIdautoUnique identifier for the image.
caption
stringA brief description of the image, intended for display as a caption or alt text.
file
objectAn object representing the image's source file.
file.id
objectIdUnique identifier for the file.
file.filename
stringOptional file name.
file.data
filedataA reference to the raw file data.
file.content_type
stringMIME content type of the file.
file.date_uploaded
dateDate the file was uploaded.
file.height
intImage height in pixels, if applicable.
file.length
intSize of the file in bytes.
file.metadata
objectA set of arbitrary data that is typically used to store custom values.
file.md5
stringAn MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
file.private
booleanIndicates whether the file is private.
file.url
stringA public URL to reference the file. Updated automatically if file content changes.
file.width
intImage width in pixels, if applicable.
meta_title
stringPage title used to override product name in storefronts.
meta_keywords
stringPage keywords used for search engine optimization purposes.
meta_description
stringPage description used for search engine optimization purposes.
options
array of objectOptions 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.
id
objectIdautoUnique identifier for the object.
name
stringrequiredHuman-friendly name of the option.
input_hint
stringSome brief hint text to help the user understand this option.
input_type
enumType 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.
parent_id
objectIdSpecifies another option ID that affects visibility of this option. The option will only appear when one of the parent_value_ids is selected.
parent_value_ids
array of child_scalarIDs of parent option values that will make the option appear if selected.
price
currencyExtra 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.
required
booleanIndicates whether the option requires a value when the product is added to a cart.
subscription
booleanIndicates whether the option specifies the billing interval of a subscription plan.
values
array of objectList of possible values for this option.
id
objectIdautoUnique identifier for the object.
name
stringrequiredHuman-friendly name of the option value.
color
stringName of the product color.
description
stringA brief description of the option value, intended for displaying to customers.
price
currencyExtra price added to the product's price/sale_price if the option value is selected. Overrides option price.
shipment_weight
floatExtra 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.
subscription_interval
enumWhen product type=subscription, this is the billing interval used when this option value is selected. Can be monthly, yearly, weekly, or daily.
Possible enum values:
subscription_interval_count
intWhen 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.
subscription_trial_days
intWhen product type=subscription, refers to a number of days offered as a trial before an invoice is issued.
image
objectImage depicting the product.
image.id
objectIdUnique identifier for the object.
image.data
filedataA reference to the raw file data.
image.date_uploaded
dateDate the file was uploaded.
image.length
intSize of the file in bytes.
image.md5
stringAn MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
image.filename
stringOptional file name.
image.content_type
stringMIME content type of the file.
image.metadata
objectArbitrary data
image.private
booleanimage.url
stringimage.width
intimage.height
intimages
array of objectid
objectIdautocaption
stringfile
objectfile.id
objectIdfile.date_uploaded
datefile.length
intfile.md5
stringfile.filename
stringfile.content_type
stringfile.metadata
objectfile.data
filedatafile.private
booleanfile.url
stringfile.width
intfile.height
intattribute_id
stringUnique identifier for the attribute.
description
stringDescription for the product options.
active
booleanIndicates the options are active.
input_multi
booleanIndicates there are multiple selections for options.
variant
booleanIndicates the option is a variant.
orig_price
currencyReflects the non-sale price of the product
price
currencyList price used when sale=false or sale_price is not defined. This value is intended for use via the frontend. See the purchase_options array to manage a product's price.
prices
array of pricePrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
price.price
currencyrequiredPrice applied when conditions are met.
price.account_group
stringCustomer account group as a condition to apply price.
price.quantity_max
intMaximum quantity as a condition to apply price.
price.quantity_min
intMinimum quantity as a condition to apply price.
quantity_min
intMinimum quantity of the product that can be sold at once.
quantity_inc
intSpecifies a quantify multiple the product must be sold in.
related_product_ids
array of child_scalarArray of related product IDs.
sale
booleanIndicates 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
currencySale price used to override list price when sale=true.
shipment_dimensions
objectrequiredProduct dimensions when packed for shipping. Typically used by third-party carriers in box packing algorithms to optimize shipping costs.
shipment_dimensions.length
floatrequiredLength of the product in unit.
shipment_dimensions.width
floatrequiredWidth of the product in unit.
shipment_dimensions.height
floatrequiredHeight of the product in unit.
shipment_dimensions.unit
enumrequiredEither in(inches) or cm(centimeters).
shipment_location
stringID of location from /settings/shipping/locations. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used.
shipment_package_quantity
floatIf specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package.
shipment_prices
array of objectProduct shipping price rules to override default shipping rules.
service
stringrequiredShipping service required for this rule to apply.
account_group
stringCustomer group required for this rule to apply.
country
stringShipping country required for this rule to apply.
fee_amount
currencyFixed amount to add when rule is applied. Only applicable when fee_type=fixed.
fee_percent
floatPercentage of the shipping price to add when rule is applied. Only applicable when fee_type=percent.
fee_type
enumType of fee to apply in addition to price, either fixed or percent.
package_quantity
intMaximum package quantity when rule is applied.
price
currencyShipping price when rule is applied.
state
stringShipping state required for this rule to apply.
total_max
currencyMaximum order subtotal for this rule to apply.
total_min
currencyMinimum order subtotal for this rule to apply.
weight_max
floatMaximum order item weight for this rule to apply.
weight_min
floatMinimum order item weight for this rule to apply.
zip
stringShipping zip/postal code required for this rule to apply.
shipment_weight
floatIf specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg—depending on the store's default weight unit.
subscription_interval
enumThe default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly, or daily.
subscription_interval_count
intMultiplier when combined with subscription_interval. For example, to make a subscription bill every two weeks, set subscription_interval=weekly and subscription_interval_count=2.
subscription_trial_days
intNumber 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.
sku
stringrequiredStock keeping unit (SKU) used to track inventory in a warehouse.
slug
stringrequiredLowercase, 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.
stock
array of StockExpandable list of stock adjustments for the product.
stock_backorder
booleanIndicates whether the product can be backordered if out of stock.
stock_level
intQuantity of the product currently in stock (including all variants), based on the sum of the stock entries.
stock_preorder
booleanIndicates whether the product can be purchased as a preorder.
stock_purchasable
booleanIndicates whether the product's stock is purchasable.
stock_status
enumautoString 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.
stock_tracking
booleanIndicates whether the product has stock tracking enabled.
summary
stringA brief product summary.
tags
array of child_scalarArray of searchable tags to aid in search discoverability.
tax_class
stringIndicates the tax class for the product.
tax_code
stringProduct tax code for tracking with Avalara, TaxJar, etc.
type
stringImplies 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.
up_sells
array of objectList of products to display as up-sells on a product detail page.
id
objectIdautoUnique identifier for the up-sell.
product_id
objectIdrequiredID of the up-sell product.
product
ProductExpandable link to the up-sell product.
variable
booleanIndicates whether the product has variant generation enabled.
virtual
booleanIndicates whether the product is virtual.
Basic pricing functionality provides the ability to designate the list price for the product and its sale_price. The list price specifies the default price of a product. When enabled, the sale_price overrides the default price.
Fields
price
currencyList price used when sale=false or sale_price is not defined. This value is intended for use via the frontend. See the purchase_options array to manage a product's price.
sale
booleanIndicates 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
currencySale price used to override list price when sale=true.
id
objectIdUnique identifier for the product.
name
stringrequiredHuman-friendly name of the product.
active
booleanIndicates whether the product is active and available in the storefront.
purchase_options
objectConfiguration 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.
purchase_options.standard
objectDesignates purchase option as a one-time purchase.
standard.id
objectIdID of the purchase option.
standard.name
stringrequiredThe name of the purchase option.
standard.description
stringA long-form description of the product. May contain HTML or other markup languages.
standard.active
booleanIndicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
standard.price
currencyList price used when sale=false or sale_price is not defined.
standard.sale
booleanIndicates 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.
standard.sale_price
currencySale price used by default when sale=true, overriding price. Overrides product sale price.
standard.prices
array of objectPrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
.price
currencyrequiredPrice applied when conditions are met.
.account_group
stringCustomer account group as a condition to apply price.
.quantity_max
intMaximum quantity as a condition to apply price.
.quantity_min
intMinimum quantity as a condition to apply price.
standard.account_groups
array of stringArray of account groups that are eligible to access the purchase option within the storefront.
purchase_options.subscription
objectDesignates purchase option for a subscription plan.
subscription.id
objectIdautoID of the subscription plan purchase option.
subscription.name
stringrequiredName of the subscription plan purchase option.
subscription.description
stringA long-form description of the purchase option. May contain HTML or other markup languages.
subscription.active
booleanIndicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
subscription.account_groups
array of stringArray of account_group names for which the purchase option is available.
subscription.plans
array of plansArray defining subscription plans and their respective configurations.
plans.id
objectIdID of the purchase option subscription plan.
plans.name
stringrequiredName of the subscription plan.
plans.description
stringA long-form description of the subscription plan. May contain HTML or other markup languages.
plans.active
booleanIndicates whether the subscription plan is available for customers to purchase. Inactive products will not be returned on the Frontend.
plans.price
currencyList price used when sale=false or sale_price is not defined.
plans.prices
array of objectPrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
.price
currencyrequiredPrice applied when conditions are met.
.account_group
stringCustomer account group as a condition to apply price.
.quantity_max
intMaximum quantity as a condition to apply price.
.quantity_min
intMinimum quantity as a condition to apply price.
plans.billing_schedule
objectrequiredDetermines the billing schedule for the subscription plan.
billing_schedule.interval
enumSubscription plan billing interval. Can be daily, weekly, monthly, or yearly.
Possible enum values:
billing_schedule.interval_count
intrequiredMultiplier for billing interval. For example, to make the billing cycle once every two weeks, set interval=weekly and interval_count=2.
billing_schedule.limit
intSpecifies 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.
billing_schedule.trial_days
intNumber of days offered as a free trial on the subscription plan before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued.
attributes
objectAn object containing custom attribute key/value pairs.
bundle
booleanIndicates whether the product is a bundle of other products.
bundle_items
array of objectList of products sold as a bundle. Applicable only when bundle=true.
id
objectIdautoUnique identifier for the bundle item.
product_id
objectIdrequiredID of the bundled product.
product
ProductExpandable link to the bundled product.
quantity
intQuantity of the bundled product. Defaults to 1.
variant_id
objectIdID of the bundled variant, if applicable.
variant
Product variantExpandable link to the bundled product variant, if applicable.
product_name
stringThis field is a copy of the item's product.name.
category
CategoryExpandable link to the primary category.
category_id
objectIdPrimary category, commonly used as a navigation anchor.
categories
CategoryExpandable link to all related product categories.
category_index
objectIndex of categories used for fast lookup operations.
category_index.id
array of child_scalarList of related product category IDs.
category_index.sort
objectIndex of category IDs and their respective sort positions.
code
stringUnique code to identify the gift card product.
cost
currencyCost of goods (COGS) used to calculate gross margins.
cross_sells
array of objectList of products to display as cross-sells on a shopping cart page.
id
objectIdautoUnique identifier for the cross-sell object.
product_id
objectIdrequiredID of the cross-sell product.
product
ProductExpandable link to the cross-sell product.
discount_type
enumType of discount to apply, either fixed or percent.
discount_amount
currencyDiscount to apply as a fixed amount. Applicable only when discount_type=fixed.
discount_percent
floatDiscount to apply as a percentage. Applicable only when discount_type=percent.
currency
stringThree-letter ISO currency code in uppercase. Defaults to your store's base currency.
customizable
booleanIndicates whether the product has custom options enabled.
date_created
dateautoDate and time the product was created.
date_updated
dateautoDate and time the product was last updated.
delivery
enumautoMethod 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.
description
stringA long-form description of the product. May contain HTML or other markup languages.
discontinued
booleanIndicates whether the product has been discontinued.
images
array of objectList of images depicting the bundle.
id
objectIdautoUnique identifier for the image.
caption
stringA brief description of the image, intended for display as a caption or alt text.
file
objectAn object representing the image's source file.
file.id
objectIdUnique identifier for the file.
file.filename
stringOptional file name.
file.data
filedataA reference to the raw file data.
file.content_type
stringMIME content type of the file.
file.date_uploaded
dateDate the file was uploaded.
file.height
intImage height in pixels, if applicable.
file.length
intSize of the file in bytes.
file.metadata
objectA set of arbitrary data that is typically used to store custom values.
file.md5
stringAn MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
file.private
booleanIndicates whether the file is private.
file.url
stringA public URL to reference the file. Updated automatically if file content changes.
file.width
intImage width in pixels, if applicable.
meta_title
stringPage title used to override product name in storefronts.
meta_keywords
stringPage keywords used for search engine optimization purposes.
meta_description
stringPage description used for search engine optimization purposes.
options
array of objectOptions 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.
id
objectIdautoUnique identifier for the object.
name
stringrequiredHuman-friendly name of the option.
input_hint
stringSome brief hint text to help the user understand this option.
input_type
enumType 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.
parent_id
objectIdSpecifies another option ID that affects visibility of this option. The option will only appear when one of the parent_value_ids is selected.
parent_value_ids
array of child_scalarIDs of parent option values that will make the option appear if selected.
price
currencyExtra 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.
required
booleanIndicates whether the option requires a value when the product is added to a cart.
subscription
booleanIndicates whether the option specifies the billing interval of a subscription plan.
values
array of objectList of possible values for this option.
id
objectIdautoUnique identifier for the object.
name
stringrequiredHuman-friendly name of the option value.
color
stringName of the product color.
description
stringA brief description of the option value, intended for displaying to customers.
price
currencyExtra price added to the product's price/sale_price if the option value is selected. Overrides option price.
shipment_weight
floatExtra 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.
subscription_interval
enumWhen product type=subscription, this is the billing interval used when this option value is selected. Can be monthly, yearly, weekly, or daily.
Possible enum values:
subscription_interval_count
intWhen 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.
subscription_trial_days
intWhen product type=subscription, refers to a number of days offered as a trial before an invoice is issued.
image
objectImage depicting the product.
image.id
objectIdUnique identifier for the object.
image.data
filedataA reference to the raw file data.
image.date_uploaded
dateDate the file was uploaded.
image.length
intSize of the file in bytes.
image.md5
stringAn MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
image.filename
stringOptional file name.
image.content_type
stringMIME content type of the file.
image.metadata
objectArbitrary data
image.private
booleanimage.url
stringimage.width
intimage.height
intimages
array of objectid
objectIdautocaption
stringfile
objectfile.id
objectIdfile.date_uploaded
datefile.length
intfile.md5
stringfile.filename
stringfile.content_type
stringfile.metadata
objectfile.data
filedatafile.private
booleanfile.url
stringfile.width
intfile.height
intattribute_id
stringUnique identifier for the attribute.
description
stringDescription for the product options.
active
booleanIndicates the options are active.
input_multi
booleanIndicates there are multiple selections for options.
variant
booleanIndicates the option is a variant.
orig_price
currencyReflects the non-sale price of the product
prices
array of pricePrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
price.price
currencyrequiredPrice applied when conditions are met.
price.account_group
stringCustomer account group as a condition to apply price.
price.quantity_max
intMaximum quantity as a condition to apply price.
price.quantity_min
intMinimum quantity as a condition to apply price.
quantity_min
intMinimum quantity of the product that can be sold at once.
quantity_inc
intSpecifies a quantify multiple the product must be sold in.
related_product_ids
array of child_scalarArray of related product IDs.
shipment_dimensions
objectrequiredProduct dimensions when packed for shipping. Typically used by third-party carriers in box packing algorithms to optimize shipping costs.
shipment_dimensions.length
floatrequiredLength of the product in unit.
shipment_dimensions.width
floatrequiredWidth of the product in unit.
shipment_dimensions.height
floatrequiredHeight of the product in unit.
shipment_dimensions.unit
enumrequiredEither in(inches) or cm(centimeters).
shipment_location
stringID of location from /settings/shipping/locations. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used.
shipment_package_quantity
floatIf specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package.
shipment_prices
array of objectProduct shipping price rules to override default shipping rules.
service
stringrequiredShipping service required for this rule to apply.
account_group
stringCustomer group required for this rule to apply.
country
stringShipping country required for this rule to apply.
fee_amount
currencyFixed amount to add when rule is applied. Only applicable when fee_type=fixed.
fee_percent
floatPercentage of the shipping price to add when rule is applied. Only applicable when fee_type=percent.
fee_type
enumType of fee to apply in addition to price, either fixed or percent.
package_quantity
intMaximum package quantity when rule is applied.
price
currencyShipping price when rule is applied.
state
stringShipping state required for this rule to apply.
total_max
currencyMaximum order subtotal for this rule to apply.
total_min
currencyMinimum order subtotal for this rule to apply.
weight_max
floatMaximum order item weight for this rule to apply.
weight_min
floatMinimum order item weight for this rule to apply.
zip
stringShipping zip/postal code required for this rule to apply.
shipment_weight
floatIf specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg—depending on the store's default weight unit.
subscription_interval
enumThe default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly, or daily.
subscription_interval_count
intMultiplier when combined with subscription_interval. For example, to make a subscription bill every two weeks, set subscription_interval=weekly and subscription_interval_count=2.
subscription_trial_days
intNumber 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.
sku
stringrequiredStock keeping unit (SKU) used to track inventory in a warehouse.
slug
stringrequiredLowercase, 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.
stock
array of StockExpandable list of stock adjustments for the product.
stock_backorder
booleanIndicates whether the product can be backordered if out of stock.
stock_level
intQuantity of the product currently in stock (including all variants), based on the sum of the stock entries.
stock_preorder
booleanIndicates whether the product can be purchased as a preorder.
stock_purchasable
booleanIndicates whether the product's stock is purchasable.
stock_status
enumautoString 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.
stock_tracking
booleanIndicates whether the product has stock tracking enabled.
summary
stringA brief product summary.
tags
array of child_scalarArray of searchable tags to aid in search discoverability.
tax_class
stringIndicates the tax class for the product.
tax_code
stringProduct tax code for tracking with Avalara, TaxJar, etc.
type
stringImplies 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.
up_sells
array of objectList of products to display as up-sells on a product detail page.
id
objectIdautoUnique identifier for the up-sell.
product_id
objectIdrequiredID of the up-sell product.
product
ProductExpandable link to the up-sell product.
variable
booleanIndicates whether the product has variant generation enabled.
variants
array of VariantsExpandable list of variants representing unique variations of the product. Each variant is a combination of one or more options. For example, Size and Color.
virtual
booleanIndicates whether the product is virtual.
Swell also allows for additional price rules. Through these, you can manage the product price for particular customer groups in addition to minimal and maximum quantities.
Fields
prices
array of pricePrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
price.price
currencyrequiredPrice applied when conditions are met.
price.account_group
stringCustomer account group as a condition to apply price.
price.quantity_max
intMaximum quantity as a condition to apply price.
price.quantity_min
intMinimum quantity as a condition to apply price.
id
objectIdUnique identifier for the product.
name
stringrequiredHuman-friendly name of the product.
active
booleanIndicates whether the product is active and available in the storefront.
purchase_options
objectConfiguration 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.
purchase_options.standard
objectDesignates purchase option as a one-time purchase.
standard.id
objectIdID of the purchase option.
standard.name
stringrequiredThe name of the purchase option.
standard.description
stringA long-form description of the product. May contain HTML or other markup languages.
standard.active
booleanIndicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
standard.price
currencyList price used when sale=false or sale_price is not defined.
standard.sale
booleanIndicates 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.
standard.sale_price
currencySale price used by default when sale=true, overriding price. Overrides product sale price.
standard.prices
array of objectPrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
.price
currencyrequiredPrice applied when conditions are met.
.account_group
stringCustomer account group as a condition to apply price.
.quantity_max
intMaximum quantity as a condition to apply price.
.quantity_min
intMinimum quantity as a condition to apply price.
standard.account_groups
array of stringArray of account groups that are eligible to access the purchase option within the storefront.
purchase_options.subscription
objectDesignates purchase option for a subscription plan.
subscription.id
objectIdautoID of the subscription plan purchase option.
subscription.name
stringrequiredName of the subscription plan purchase option.
subscription.description
stringA long-form description of the purchase option. May contain HTML or other markup languages.
subscription.active
booleanIndicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
subscription.account_groups
array of stringArray of account_group names for which the purchase option is available.
subscription.plans
array of plansArray defining subscription plans and their respective configurations.
plans.id
objectIdID of the purchase option subscription plan.
plans.name
stringrequiredName of the subscription plan.
plans.description
stringA long-form description of the subscription plan. May contain HTML or other markup languages.
plans.active
booleanIndicates whether the subscription plan is available for customers to purchase. Inactive products will not be returned on the Frontend.
plans.price
currencyList price used when sale=false or sale_price is not defined.
plans.prices
array of objectPrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
.price
currencyrequiredPrice applied when conditions are met.
.account_group
stringCustomer account group as a condition to apply price.
.quantity_max
intMaximum quantity as a condition to apply price.
.quantity_min
intMinimum quantity as a condition to apply price.
plans.billing_schedule
objectrequiredDetermines the billing schedule for the subscription plan.
billing_schedule.interval
enumSubscription plan billing interval. Can be daily, weekly, monthly, or yearly.
Possible enum values:
billing_schedule.interval_count
intrequiredMultiplier for billing interval. For example, to make the billing cycle once every two weeks, set interval=weekly and interval_count=2.
billing_schedule.limit
intSpecifies 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.
billing_schedule.trial_days
intNumber of days offered as a free trial on the subscription plan before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued.
attributes
objectAn object containing custom attribute key/value pairs.
bundle
booleanIndicates whether the product is a bundle of other products.
bundle_items
array of objectList of products sold as a bundle. Applicable only when bundle=true.
id
objectIdautoUnique identifier for the bundle item.
product_id
objectIdrequiredID of the bundled product.
product
ProductExpandable link to the bundled product.
quantity
intQuantity of the bundled product. Defaults to 1.
variant_id
objectIdID of the bundled variant, if applicable.
variant
Product variantExpandable link to the bundled product variant, if applicable.
product_name
stringThis field is a copy of the item's product.name.
category
CategoryExpandable link to the primary category.
category_id
objectIdPrimary category, commonly used as a navigation anchor.
categories
CategoryExpandable link to all related product categories.
category_index
objectIndex of categories used for fast lookup operations.
category_index.id
array of child_scalarList of related product category IDs.
category_index.sort
objectIndex of category IDs and their respective sort positions.
code
stringUnique code to identify the gift card product.
cost
currencyCost of goods (COGS) used to calculate gross margins.
cross_sells
array of objectList of products to display as cross-sells on a shopping cart page.
id
objectIdautoUnique identifier for the cross-sell object.
product_id
objectIdrequiredID of the cross-sell product.
product
ProductExpandable link to the cross-sell product.
discount_type
enumType of discount to apply, either fixed or percent.
discount_amount
currencyDiscount to apply as a fixed amount. Applicable only when discount_type=fixed.
discount_percent
floatDiscount to apply as a percentage. Applicable only when discount_type=percent.
currency
stringThree-letter ISO currency code in uppercase. Defaults to your store's base currency.
customizable
booleanIndicates whether the product has custom options enabled.
date_created
dateautoDate and time the product was created.
date_updated
dateautoDate and time the product was last updated.
delivery
enumautoMethod 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.
description
stringA long-form description of the product. May contain HTML or other markup languages.
discontinued
booleanIndicates whether the product has been discontinued.
images
array of objectList of images depicting the bundle.
id
objectIdautoUnique identifier for the image.
caption
stringA brief description of the image, intended for display as a caption or alt text.
file
objectAn object representing the image's source file.
file.id
objectIdUnique identifier for the file.
file.filename
stringOptional file name.
file.data
filedataA reference to the raw file data.
file.content_type
stringMIME content type of the file.
file.date_uploaded
dateDate the file was uploaded.
file.height
intImage height in pixels, if applicable.
file.length
intSize of the file in bytes.
file.metadata
objectA set of arbitrary data that is typically used to store custom values.
file.md5
stringAn MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
file.private
booleanIndicates whether the file is private.
file.url
stringA public URL to reference the file. Updated automatically if file content changes.
file.width
intImage width in pixels, if applicable.
meta_title
stringPage title used to override product name in storefronts.
meta_keywords
stringPage keywords used for search engine optimization purposes.
meta_description
stringPage description used for search engine optimization purposes.
options
array of objectOptions 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.
id
objectIdautoUnique identifier for the object.
name
stringrequiredHuman-friendly name of the option.
input_hint
stringSome brief hint text to help the user understand this option.
input_type
enumType 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.
parent_id
objectIdSpecifies another option ID that affects visibility of this option. The option will only appear when one of the parent_value_ids is selected.
parent_value_ids
array of child_scalarIDs of parent option values that will make the option appear if selected.
price
currencyExtra 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.
required
booleanIndicates whether the option requires a value when the product is added to a cart.
subscription
booleanIndicates whether the option specifies the billing interval of a subscription plan.
values
array of objectList of possible values for this option.
id
objectIdautoUnique identifier for the object.
name
stringrequiredHuman-friendly name of the option value.
color
stringName of the product color.
description
stringA brief description of the option value, intended for displaying to customers.
price
currencyExtra price added to the product's price/sale_price if the option value is selected. Overrides option price.
shipment_weight
floatExtra 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.
subscription_interval
enumWhen product type=subscription, this is the billing interval used when this option value is selected. Can be monthly, yearly, weekly, or daily.
Possible enum values:
subscription_interval_count
intWhen 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.
subscription_trial_days
intWhen product type=subscription, refers to a number of days offered as a trial before an invoice is issued.
image
objectImage depicting the product.
image.id
objectIdUnique identifier for the object.
image.data
filedataA reference to the raw file data.
image.date_uploaded
dateDate the file was uploaded.
image.length
intSize of the file in bytes.
image.md5
stringAn MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
image.filename
stringOptional file name.
image.content_type
stringMIME content type of the file.
image.metadata
objectArbitrary data
image.private
booleanimage.url
stringimage.width
intimage.height
intimages
array of objectid
objectIdautocaption
stringfile
objectfile.id
objectIdfile.date_uploaded
datefile.length
intfile.md5
stringfile.filename
stringfile.content_type
stringfile.metadata
objectfile.data
filedatafile.private
booleanfile.url
stringfile.width
intfile.height
intattribute_id
stringUnique identifier for the attribute.
description
stringDescription for the product options.
active
booleanIndicates the options are active.
input_multi
booleanIndicates there are multiple selections for options.
variant
booleanIndicates the option is a variant.
orig_price
currencyReflects the non-sale price of the product
price
currencyList price used when sale=false or sale_price is not defined. This value is intended for use via the frontend. See the purchase_options array to manage a product's price.
quantity_min
intMinimum quantity of the product that can be sold at once.
quantity_inc
intSpecifies a quantify multiple the product must be sold in.
related_product_ids
array of child_scalarArray of related product IDs.
sale
booleanIndicates 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
currencySale price used to override list price when sale=true.
shipment_dimensions
objectrequiredProduct dimensions when packed for shipping. Typically used by third-party carriers in box packing algorithms to optimize shipping costs.
shipment_dimensions.length
floatrequiredLength of the product in unit.
shipment_dimensions.width
floatrequiredWidth of the product in unit.
shipment_dimensions.height
floatrequiredHeight of the product in unit.
shipment_dimensions.unit
enumrequiredEither in(inches) or cm(centimeters).
shipment_location
stringID of location from /settings/shipping/locations. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used.
shipment_package_quantity
floatIf specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package.
shipment_prices
array of objectProduct shipping price rules to override default shipping rules.
service
stringrequiredShipping service required for this rule to apply.
account_group
stringCustomer group required for this rule to apply.
country
stringShipping country required for this rule to apply.
fee_amount
currencyFixed amount to add when rule is applied. Only applicable when fee_type=fixed.
fee_percent
floatPercentage of the shipping price to add when rule is applied. Only applicable when fee_type=percent.
fee_type
enumType of fee to apply in addition to price, either fixed or percent.
package_quantity
intMaximum package quantity when rule is applied.
price
currencyShipping price when rule is applied.
state
stringShipping state required for this rule to apply.
total_max
currencyMaximum order subtotal for this rule to apply.
total_min
currencyMinimum order subtotal for this rule to apply.
weight_max
floatMaximum order item weight for this rule to apply.
weight_min
floatMinimum order item weight for this rule to apply.
zip
stringShipping zip/postal code required for this rule to apply.
shipment_weight
floatIf specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg—depending on the store's default weight unit.
subscription_interval
enumThe default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly, or daily.
subscription_interval_count
intMultiplier when combined with subscription_interval. For example, to make a subscription bill every two weeks, set subscription_interval=weekly and subscription_interval_count=2.
subscription_trial_days
intNumber 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.
sku
stringrequiredStock keeping unit (SKU) used to track inventory in a warehouse.
slug
stringrequiredLowercase, 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.
stock
array of StockExpandable list of stock adjustments for the product.
stock_backorder
booleanIndicates whether the product can be backordered if out of stock.
stock_level
intQuantity of the product currently in stock (including all variants), based on the sum of the stock entries.
stock_preorder
booleanIndicates whether the product can be purchased as a preorder.
stock_purchasable
booleanIndicates whether the product's stock is purchasable.
stock_status
enumautoString 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.
stock_tracking
booleanIndicates whether the product has stock tracking enabled.
summary
stringA brief product summary.
tags
array of child_scalarArray of searchable tags to aid in search discoverability.
tax_class
stringIndicates the tax class for the product.
tax_code
stringProduct tax code for tracking with Avalara, TaxJar, etc.
type
stringImplies 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.
up_sells
array of objectList of products to display as up-sells on a product detail page.
id
objectIdautoUnique identifier for the up-sell.
product_id
objectIdrequiredID of the up-sell product.
product
ProductExpandable link to the up-sell product.
variable
booleanIndicates whether the product has variant generation enabled.
variants
array of VariantsExpandable list of variants representing unique variations of the product. Each variant is a combination of one or more options. For example, Size and Color.
virtual
booleanIndicates whether the product is virtual.
Designate which products a customer would see when on a particular product page by designating additional products as up_sells or cross_sells.
Fields
cross_sells
array of objectList of products to display as cross-sells on a shopping cart page.
id
objectIdautoUnique identifier for the cross-sell object.
product_id
objectIdrequiredID of the cross-sell product.
product
ProductExpandable link to the cross-sell product.
discount_type
enumType of discount to apply, either fixed or percent.
discount_amount
currencyDiscount to apply as a fixed amount. Applicable only when discount_type=fixed.
discount_percent
floatDiscount to apply as a percentage. Applicable only when discount_type=percent.
up_sells
array of objectList of products to display as up-sells on a product detail page.
id
objectIdautoUnique identifier for the up-sell.
product_id
objectIdrequiredID of the up-sell product.
product
ProductExpandable link to the up-sell product.
id
objectIdUnique identifier for the product.
name
stringrequiredHuman-friendly name of the product.
active
booleanIndicates whether the product is active and available in the storefront.
purchase_options
objectConfiguration 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.
purchase_options.standard
objectDesignates purchase option as a one-time purchase.
standard.id
objectIdID of the purchase option.
standard.name
stringrequiredThe name of the purchase option.
standard.description
stringA long-form description of the product. May contain HTML or other markup languages.
standard.active
booleanIndicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
standard.price
currencyList price used when sale=false or sale_price is not defined.
standard.sale
booleanIndicates 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.
standard.sale_price
currencySale price used by default when sale=true, overriding price. Overrides product sale price.
standard.prices
array of objectPrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
.price
currencyrequiredPrice applied when conditions are met.
.account_group
stringCustomer account group as a condition to apply price.
.quantity_max
intMaximum quantity as a condition to apply price.
.quantity_min
intMinimum quantity as a condition to apply price.
standard.account_groups
array of stringArray of account groups that are eligible to access the purchase option within the storefront.
purchase_options.subscription
objectDesignates purchase option for a subscription plan.
subscription.id
objectIdautoID of the subscription plan purchase option.
subscription.name
stringrequiredName of the subscription plan purchase option.
subscription.description
stringA long-form description of the purchase option. May contain HTML or other markup languages.
subscription.active
booleanIndicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
subscription.account_groups
array of stringArray of account_group names for which the purchase option is available.
subscription.plans
array of plansArray defining subscription plans and their respective configurations.
plans.id
objectIdID of the purchase option subscription plan.
plans.name
stringrequiredName of the subscription plan.
plans.description
stringA long-form description of the subscription plan. May contain HTML or other markup languages.
plans.active
booleanIndicates whether the subscription plan is available for customers to purchase. Inactive products will not be returned on the Frontend.
plans.price
currencyList price used when sale=false or sale_price is not defined.
plans.prices
array of objectPrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
.price
currencyrequiredPrice applied when conditions are met.
.account_group
stringCustomer account group as a condition to apply price.
.quantity_max
intMaximum quantity as a condition to apply price.
.quantity_min
intMinimum quantity as a condition to apply price.
plans.billing_schedule
objectrequiredDetermines the billing schedule for the subscription plan.
billing_schedule.interval
enumSubscription plan billing interval. Can be daily, weekly, monthly, or yearly.
Possible enum values:
billing_schedule.interval_count
intrequiredMultiplier for billing interval. For example, to make the billing cycle once every two weeks, set interval=weekly and interval_count=2.
billing_schedule.limit
intSpecifies 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.
billing_schedule.trial_days
intNumber of days offered as a free trial on the subscription plan before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued.
attributes
objectAn object containing custom attribute key/value pairs.
bundle
booleanIndicates whether the product is a bundle of other products.
bundle_items
array of objectList of products sold as a bundle. Applicable only when bundle=true.
id
objectIdautoUnique identifier for the bundle item.
product_id
objectIdrequiredID of the bundled product.
product
ProductExpandable link to the bundled product.
quantity
intQuantity of the bundled product. Defaults to 1.
variant_id
objectIdID of the bundled variant, if applicable.
variant
Product variantExpandable link to the bundled product variant, if applicable.
product_name
stringThis field is a copy of the item's product.name.
category
CategoryExpandable link to the primary category.
category_id
objectIdPrimary category, commonly used as a navigation anchor.
categories
CategoryExpandable link to all related product categories.
category_index
objectIndex of categories used for fast lookup operations.
category_index.id
array of child_scalarList of related product category IDs.
category_index.sort
objectIndex of category IDs and their respective sort positions.
code
stringUnique code to identify the gift card product.
cost
currencyCost of goods (COGS) used to calculate gross margins.
currency
stringThree-letter ISO currency code in uppercase. Defaults to your store's base currency.
customizable
booleanIndicates whether the product has custom options enabled.
date_created
dateautoDate and time the product was created.
date_updated
dateautoDate and time the product was last updated.
delivery
enumautoMethod 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.
description
stringA long-form description of the product. May contain HTML or other markup languages.
discontinued
booleanIndicates whether the product has been discontinued.
images
array of objectList of images depicting the bundle.
id
objectIdautoUnique identifier for the image.
caption
stringA brief description of the image, intended for display as a caption or alt text.
file
objectAn object representing the image's source file.
file.id
objectIdUnique identifier for the file.
file.filename
stringOptional file name.
file.data
filedataA reference to the raw file data.
file.content_type
stringMIME content type of the file.
file.date_uploaded
dateDate the file was uploaded.
file.height
intImage height in pixels, if applicable.
file.length
intSize of the file in bytes.
file.metadata
objectA set of arbitrary data that is typically used to store custom values.
file.md5
stringAn MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
file.private
booleanIndicates whether the file is private.
file.url
stringA public URL to reference the file. Updated automatically if file content changes.
file.width
intImage width in pixels, if applicable.
meta_title
stringPage title used to override product name in storefronts.
meta_keywords
stringPage keywords used for search engine optimization purposes.
meta_description
stringPage description used for search engine optimization purposes.
options
array of objectOptions 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.
id
objectIdautoUnique identifier for the object.
name
stringrequiredHuman-friendly name of the option.
input_hint
stringSome brief hint text to help the user understand this option.
input_type
enumType 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.
parent_id
objectIdSpecifies another option ID that affects visibility of this option. The option will only appear when one of the parent_value_ids is selected.
parent_value_ids
array of child_scalarIDs of parent option values that will make the option appear if selected.
price
currencyExtra 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.
required
booleanIndicates whether the option requires a value when the product is added to a cart.
subscription
booleanIndicates whether the option specifies the billing interval of a subscription plan.
values
array of objectList of possible values for this option.
id
objectIdautoUnique identifier for the object.
name
stringrequiredHuman-friendly name of the option value.
color
stringName of the product color.
description
stringA brief description of the option value, intended for displaying to customers.
price
currencyExtra price added to the product's price/sale_price if the option value is selected. Overrides option price.
shipment_weight
floatExtra 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.
subscription_interval
enumWhen product type=subscription, this is the billing interval used when this option value is selected. Can be monthly, yearly, weekly, or daily.
Possible enum values:
subscription_interval_count
intWhen 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.
subscription_trial_days
intWhen product type=subscription, refers to a number of days offered as a trial before an invoice is issued.
image
objectImage depicting the product.
image.id
objectIdUnique identifier for the object.
image.data
filedataA reference to the raw file data.
image.date_uploaded
dateDate the file was uploaded.
image.length
intSize of the file in bytes.
image.md5
stringAn MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
image.filename
stringOptional file name.
image.content_type
stringMIME content type of the file.
image.metadata
objectArbitrary data
image.private
booleanimage.url
stringimage.width
intimage.height
intimages
array of objectid
objectIdautocaption
stringfile
objectfile.id
objectIdfile.date_uploaded
datefile.length
intfile.md5
stringfile.filename
stringfile.content_type
stringfile.metadata
objectfile.data
filedatafile.private
booleanfile.url
stringfile.width
intfile.height
intattribute_id
stringUnique identifier for the attribute.
description
stringDescription for the product options.
active
booleanIndicates the options are active.
input_multi
booleanIndicates there are multiple selections for options.
variant
booleanIndicates the option is a variant.
orig_price
currencyReflects the non-sale price of the product
price
currencyList price used when sale=false or sale_price is not defined. This value is intended for use via the frontend. See the purchase_options array to manage a product's price.
prices
array of pricePrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
price.price
currencyrequiredPrice applied when conditions are met.
price.account_group
stringCustomer account group as a condition to apply price.
price.quantity_max
intMaximum quantity as a condition to apply price.
price.quantity_min
intMinimum quantity as a condition to apply price.
quantity_min
intMinimum quantity of the product that can be sold at once.
quantity_inc
intSpecifies a quantify multiple the product must be sold in.
related_product_ids
array of child_scalarArray of related product IDs.
sale
booleanIndicates 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
currencySale price used to override list price when sale=true.
shipment_dimensions
objectrequiredProduct dimensions when packed for shipping. Typically used by third-party carriers in box packing algorithms to optimize shipping costs.
shipment_dimensions.length
floatrequiredLength of the product in unit.
shipment_dimensions.width
floatrequiredWidth of the product in unit.
shipment_dimensions.height
floatrequiredHeight of the product in unit.
shipment_dimensions.unit
enumrequiredEither in(inches) or cm(centimeters).
shipment_location
stringID of location from /settings/shipping/locations. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used.
shipment_package_quantity
floatIf specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package.
shipment_prices
array of objectProduct shipping price rules to override default shipping rules.
service
stringrequiredShipping service required for this rule to apply.
account_group
stringCustomer group required for this rule to apply.
country
stringShipping country required for this rule to apply.
fee_amount
currencyFixed amount to add when rule is applied. Only applicable when fee_type=fixed.
fee_percent
floatPercentage of the shipping price to add when rule is applied. Only applicable when fee_type=percent.
fee_type
enumType of fee to apply in addition to price, either fixed or percent.
package_quantity
intMaximum package quantity when rule is applied.
price
currencyShipping price when rule is applied.
state
stringShipping state required for this rule to apply.
total_max
currencyMaximum order subtotal for this rule to apply.
total_min
currencyMinimum order subtotal for this rule to apply.
weight_max
floatMaximum order item weight for this rule to apply.
weight_min
floatMinimum order item weight for this rule to apply.
zip
stringShipping zip/postal code required for this rule to apply.
shipment_weight
floatIf specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg—depending on the store's default weight unit.
subscription_interval
enumThe default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly, or daily.
subscription_interval_count
intMultiplier when combined with subscription_interval. For example, to make a subscription bill every two weeks, set subscription_interval=weekly and subscription_interval_count=2.
subscription_trial_days
intNumber 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.
sku
stringrequiredStock keeping unit (SKU) used to track inventory in a warehouse.
slug
stringrequiredLowercase, 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.
stock
array of StockExpandable list of stock adjustments for the product.
stock_backorder
booleanIndicates whether the product can be backordered if out of stock.
stock_level
intQuantity of the product currently in stock (including all variants), based on the sum of the stock entries.
stock_preorder
booleanIndicates whether the product can be purchased as a preorder.
stock_purchasable
booleanIndicates whether the product's stock is purchasable.
stock_status
enumautoString 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.
stock_tracking
booleanIndicates whether the product has stock tracking enabled.
summary
stringA brief product summary.
tags
array of child_scalarArray of searchable tags to aid in search discoverability.
tax_class
stringIndicates the tax class for the product.
tax_code
stringProduct tax code for tracking with Avalara, TaxJar, etc.
type
stringImplies 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.
variable
booleanIndicates whether the product has variant generation enabled.
variants
array of VariantsExpandable list of variants representing unique variations of the product. Each variant is a combination of one or more options. For example, Size and Color.
virtual
booleanIndicates whether the product is virtual.
The content section includes several fields—all geared towards describing your product. Use these to optimize for SEO and to provide information for individual products. You can also add additional content fields.
Fields
You can manage product inventory within the Inventory tab by enabling inventory tracking. There is also an option to allow purchases on the product when it is out of stock. When managing a product's inventory, each product variant has its own dedicated inventory to track stock levels.
Fields
stock_level
intQuantity of the product currently in stock (including all variants), based on the sum of the stock entries.
stock_status
enumautoString 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.
stock_tracking
booleanIndicates whether the product has stock tracking enabled.
id
objectIdUnique identifier for the product.
name
stringrequiredHuman-friendly name of the product.
active
booleanIndicates whether the product is active and available in the storefront.
purchase_options
objectConfiguration 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.
purchase_options.standard
objectDesignates purchase option as a one-time purchase.
standard.id
objectIdID of the purchase option.
standard.name
stringrequiredThe name of the purchase option.
standard.description
stringA long-form description of the product. May contain HTML or other markup languages.
standard.active
booleanIndicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
standard.price
currencyList price used when sale=false or sale_price is not defined.
standard.sale
booleanIndicates 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.
standard.sale_price
currencySale price used by default when sale=true, overriding price. Overrides product sale price.
standard.prices
array of objectPrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
.price
currencyrequiredPrice applied when conditions are met.
.account_group
stringCustomer account group as a condition to apply price.
.quantity_max
intMaximum quantity as a condition to apply price.
.quantity_min
intMinimum quantity as a condition to apply price.
standard.account_groups
array of stringArray of account groups that are eligible to access the purchase option within the storefront.
purchase_options.subscription
objectDesignates purchase option for a subscription plan.
subscription.id
objectIdautoID of the subscription plan purchase option.
subscription.name
stringrequiredName of the subscription plan purchase option.
subscription.description
stringA long-form description of the purchase option. May contain HTML or other markup languages.
subscription.active
booleanIndicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
subscription.account_groups
array of stringArray of account_group names for which the purchase option is available.
subscription.plans
array of plansArray defining subscription plans and their respective configurations.
plans.id
objectIdID of the purchase option subscription plan.
plans.name
stringrequiredName of the subscription plan.
plans.description
stringA long-form description of the subscription plan. May contain HTML or other markup languages.
plans.active
booleanIndicates whether the subscription plan is available for customers to purchase. Inactive products will not be returned on the Frontend.
plans.price
currencyList price used when sale=false or sale_price is not defined.
plans.prices
array of objectPrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
.price
currencyrequiredPrice applied when conditions are met.
.account_group
stringCustomer account group as a condition to apply price.
.quantity_max
intMaximum quantity as a condition to apply price.
.quantity_min
intMinimum quantity as a condition to apply price.
plans.billing_schedule
objectrequiredDetermines the billing schedule for the subscription plan.
billing_schedule.interval
enumSubscription plan billing interval. Can be daily, weekly, monthly, or yearly.
Possible enum values:
billing_schedule.interval_count
intrequiredMultiplier for billing interval. For example, to make the billing cycle once every two weeks, set interval=weekly and interval_count=2.
billing_schedule.limit
intSpecifies 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.
billing_schedule.trial_days
intNumber of days offered as a free trial on the subscription plan before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued.
attributes
objectAn object containing custom attribute key/value pairs.
bundle
booleanIndicates whether the product is a bundle of other products.
bundle_items
array of objectList of products sold as a bundle. Applicable only when bundle=true.
id
objectIdautoUnique identifier for the bundle item.
product_id
objectIdrequiredID of the bundled product.
product
ProductExpandable link to the bundled product.
quantity
intQuantity of the bundled product. Defaults to 1.
variant_id
objectIdID of the bundled variant, if applicable.
variant
Product variantExpandable link to the bundled product variant, if applicable.
product_name
stringThis field is a copy of the item's product.name.
category
CategoryExpandable link to the primary category.
category_id
objectIdPrimary category, commonly used as a navigation anchor.
categories
CategoryExpandable link to all related product categories.
category_index
objectIndex of categories used for fast lookup operations.
category_index.id
array of child_scalarList of related product category IDs.
category_index.sort
objectIndex of category IDs and their respective sort positions.
code
stringUnique code to identify the gift card product.
cost
currencyCost of goods (COGS) used to calculate gross margins.
cross_sells
array of objectList of products to display as cross-sells on a shopping cart page.
id
objectIdautoUnique identifier for the cross-sell object.
product_id
objectIdrequiredID of the cross-sell product.
product
ProductExpandable link to the cross-sell product.
discount_type
enumType of discount to apply, either fixed or percent.
discount_amount
currencyDiscount to apply as a fixed amount. Applicable only when discount_type=fixed.
discount_percent
floatDiscount to apply as a percentage. Applicable only when discount_type=percent.
currency
stringThree-letter ISO currency code in uppercase. Defaults to your store's base currency.
customizable
booleanIndicates whether the product has custom options enabled.
date_created
dateautoDate and time the product was created.
date_updated
dateautoDate and time the product was last updated.
delivery
enumautoMethod 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.
description
stringA long-form description of the product. May contain HTML or other markup languages.
discontinued
booleanIndicates whether the product has been discontinued.
images
array of objectList of images depicting the bundle.
id
objectIdautoUnique identifier for the image.
caption
stringA brief description of the image, intended for display as a caption or alt text.
file
objectAn object representing the image's source file.
file.id
objectIdUnique identifier for the file.
file.filename
stringOptional file name.
file.data
filedataA reference to the raw file data.
file.content_type
stringMIME content type of the file.
file.date_uploaded
dateDate the file was uploaded.
file.height
intImage height in pixels, if applicable.
file.length
intSize of the file in bytes.
file.metadata
objectA set of arbitrary data that is typically used to store custom values.
file.md5
stringAn MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
file.private
booleanIndicates whether the file is private.
file.url
stringA public URL to reference the file. Updated automatically if file content changes.
file.width
intImage width in pixels, if applicable.
meta_title
stringPage title used to override product name in storefronts.
meta_keywords
stringPage keywords used for search engine optimization purposes.
meta_description
stringPage description used for search engine optimization purposes.
options
array of objectOptions 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.
id
objectIdautoUnique identifier for the object.
name
stringrequiredHuman-friendly name of the option.
input_hint
stringSome brief hint text to help the user understand this option.
input_type
enumType 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.
parent_id
objectIdSpecifies another option ID that affects visibility of this option. The option will only appear when one of the parent_value_ids is selected.
parent_value_ids
array of child_scalarIDs of parent option values that will make the option appear if selected.
price
currencyExtra 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.
required
booleanIndicates whether the option requires a value when the product is added to a cart.
subscription
booleanIndicates whether the option specifies the billing interval of a subscription plan.
values
array of objectList of possible values for this option.
id
objectIdautoUnique identifier for the object.
name
stringrequiredHuman-friendly name of the option value.
color
stringName of the product color.
description
stringA brief description of the option value, intended for displaying to customers.
price
currencyExtra price added to the product's price/sale_price if the option value is selected. Overrides option price.
shipment_weight
floatExtra 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.
subscription_interval
enumWhen product type=subscription, this is the billing interval used when this option value is selected. Can be monthly, yearly, weekly, or daily.
Possible enum values:
subscription_interval_count
intWhen 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.
subscription_trial_days
intWhen product type=subscription, refers to a number of days offered as a trial before an invoice is issued.
image
objectImage depicting the product.
image.id
objectIdUnique identifier for the object.
image.data
filedataA reference to the raw file data.
image.date_uploaded
dateDate the file was uploaded.
image.length
intSize of the file in bytes.
image.md5
stringAn MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
image.filename
stringOptional file name.
image.content_type
stringMIME content type of the file.
image.metadata
objectArbitrary data
image.private
booleanimage.url
stringimage.width
intimage.height
intimages
array of objectid
objectIdautocaption
stringfile
objectfile.id
objectIdfile.date_uploaded
datefile.length
intfile.md5
stringfile.filename
stringfile.content_type
stringfile.metadata
objectfile.data
filedatafile.private
booleanfile.url
stringfile.width
intfile.height
intattribute_id
stringUnique identifier for the attribute.
description
stringDescription for the product options.
active
booleanIndicates the options are active.
input_multi
booleanIndicates there are multiple selections for options.
variant
booleanIndicates the option is a variant.
orig_price
currencyReflects the non-sale price of the product
price
currencyList price used when sale=false or sale_price is not defined. This value is intended for use via the frontend. See the purchase_options array to manage a product's price.
prices
array of pricePrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
price.price
currencyrequiredPrice applied when conditions are met.
price.account_group
stringCustomer account group as a condition to apply price.
price.quantity_max
intMaximum quantity as a condition to apply price.
price.quantity_min
intMinimum quantity as a condition to apply price.
quantity_min
intMinimum quantity of the product that can be sold at once.
quantity_inc
intSpecifies a quantify multiple the product must be sold in.
related_product_ids
array of child_scalarArray of related product IDs.
sale
booleanIndicates 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
currencySale price used to override list price when sale=true.
shipment_dimensions
objectrequiredProduct dimensions when packed for shipping. Typically used by third-party carriers in box packing algorithms to optimize shipping costs.
shipment_dimensions.length
floatrequiredLength of the product in unit.
shipment_dimensions.width
floatrequiredWidth of the product in unit.
shipment_dimensions.height
floatrequiredHeight of the product in unit.
shipment_dimensions.unit
enumrequiredEither in(inches) or cm(centimeters).
shipment_location
stringID of location from /settings/shipping/locations. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used.
shipment_package_quantity
floatIf specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package.
shipment_prices
array of objectProduct shipping price rules to override default shipping rules.
service
stringrequiredShipping service required for this rule to apply.
account_group
stringCustomer group required for this rule to apply.
country
stringShipping country required for this rule to apply.
fee_amount
currencyFixed amount to add when rule is applied. Only applicable when fee_type=fixed.
fee_percent
floatPercentage of the shipping price to add when rule is applied. Only applicable when fee_type=percent.
fee_type
enumType of fee to apply in addition to price, either fixed or percent.
package_quantity
intMaximum package quantity when rule is applied.
price
currencyShipping price when rule is applied.
state
stringShipping state required for this rule to apply.
total_max
currencyMaximum order subtotal for this rule to apply.
total_min
currencyMinimum order subtotal for this rule to apply.
weight_max
floatMaximum order item weight for this rule to apply.
weight_min
floatMinimum order item weight for this rule to apply.
zip
stringShipping zip/postal code required for this rule to apply.
shipment_weight
floatIf specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg—depending on the store's default weight unit.
subscription_interval
enumThe default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly, or daily.
subscription_interval_count
intMultiplier when combined with subscription_interval. For example, to make a subscription bill every two weeks, set subscription_interval=weekly and subscription_interval_count=2.
subscription_trial_days
intNumber 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.
sku
stringrequiredStock keeping unit (SKU) used to track inventory in a warehouse.
slug
stringrequiredLowercase, 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.
stock
array of StockExpandable list of stock adjustments for the product.
stock_backorder
booleanIndicates whether the product can be backordered if out of stock.
stock_preorder
booleanIndicates whether the product can be purchased as a preorder.
stock_purchasable
booleanIndicates whether the product's stock is purchasable.
summary
stringA brief product summary.
tags
array of child_scalarArray of searchable tags to aid in search discoverability.
tax_class
stringIndicates the tax class for the product.
tax_code
stringProduct tax code for tracking with Avalara, TaxJar, etc.
type
stringImplies 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.
up_sells
array of objectList of products to display as up-sells on a product detail page.
id
objectIdautoUnique identifier for the up-sell.
product_id
objectIdrequiredID of the up-sell product.
product
ProductExpandable link to the up-sell product.
variable
booleanIndicates whether the product has variant generation enabled.
variants
array of VariantsExpandable list of variants representing unique variations of the product. Each variant is a combination of one or more options. For example, Size and Color.
virtual
booleanIndicates whether the product is virtual.
Unless you have a pickup option enabled as a shipping service, you must ship physical products to the customer. Shipping properties are where you define a product's weight, dimensions, and packing constraints. When enabled, these are used to calculate shipping costs. Additionally, shipping rules for individual products override your default storewide shipping settings.
Fields
shipment_dimensions
objectrequiredProduct dimensions when packed for shipping. Typically used by third-party carriers in box packing algorithms to optimize shipping costs.
shipment_dimensions.length
floatrequiredLength of the product in unit.
shipment_dimensions.width
floatrequiredWidth of the product in unit.
shipment_dimensions.height
floatrequiredHeight of the product in unit.
shipment_dimensions.unit
enumrequiredEither in(inches) or cm(centimeters).
shipment_location
stringID of location from /settings/shipping/locations. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used.
shipment_prices
array of objectProduct shipping price rules to override default shipping rules.
service
stringrequiredShipping service required for this rule to apply.
account_group
stringCustomer group required for this rule to apply.
country
stringShipping country required for this rule to apply.
fee_amount
currencyFixed amount to add when rule is applied. Only applicable when fee_type=fixed.
fee_percent
floatPercentage of the shipping price to add when rule is applied. Only applicable when fee_type=percent.
fee_type
enumType of fee to apply in addition to price, either fixed or percent.
package_quantity
intMaximum package quantity when rule is applied.
price
currencyShipping price when rule is applied.
state
stringShipping state required for this rule to apply.
total_max
currencyMaximum order subtotal for this rule to apply.
total_min
currencyMinimum order subtotal for this rule to apply.
weight_max
floatMaximum order item weight for this rule to apply.
weight_min
floatMinimum order item weight for this rule to apply.
zip
stringShipping zip/postal code required for this rule to apply.
shipment_weight
floatIf specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg—depending on the store's default weight unit.
id
objectIdUnique identifier for the product.
name
stringrequiredHuman-friendly name of the product.
active
booleanIndicates whether the product is active and available in the storefront.
purchase_options
objectConfiguration 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.
purchase_options.standard
objectDesignates purchase option as a one-time purchase.
standard.id
objectIdID of the purchase option.
standard.name
stringrequiredThe name of the purchase option.
standard.description
stringA long-form description of the product. May contain HTML or other markup languages.
standard.active
booleanIndicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
standard.price
currencyList price used when sale=false or sale_price is not defined.
standard.sale
booleanIndicates 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.
standard.sale_price
currencySale price used by default when sale=true, overriding price. Overrides product sale price.
standard.prices
array of objectPrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
.price
currencyrequiredPrice applied when conditions are met.
.account_group
stringCustomer account group as a condition to apply price.
.quantity_max
intMaximum quantity as a condition to apply price.
.quantity_min
intMinimum quantity as a condition to apply price.
standard.account_groups
array of stringArray of account groups that are eligible to access the purchase option within the storefront.
purchase_options.subscription
objectDesignates purchase option for a subscription plan.
subscription.id
objectIdautoID of the subscription plan purchase option.
subscription.name
stringrequiredName of the subscription plan purchase option.
subscription.description
stringA long-form description of the purchase option. May contain HTML or other markup languages.
subscription.active
booleanIndicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
subscription.account_groups
array of stringArray of account_group names for which the purchase option is available.
subscription.plans
array of plansArray defining subscription plans and their respective configurations.
plans.id
objectIdID of the purchase option subscription plan.
plans.name
stringrequiredName of the subscription plan.
plans.description
stringA long-form description of the subscription plan. May contain HTML or other markup languages.
plans.active
booleanIndicates whether the subscription plan is available for customers to purchase. Inactive products will not be returned on the Frontend.
plans.price
currencyList price used when sale=false or sale_price is not defined.
plans.prices
array of objectPrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
.price
currencyrequiredPrice applied when conditions are met.
.account_group
stringCustomer account group as a condition to apply price.
.quantity_max
intMaximum quantity as a condition to apply price.
.quantity_min
intMinimum quantity as a condition to apply price.
plans.billing_schedule
objectrequiredDetermines the billing schedule for the subscription plan.
billing_schedule.interval
enumSubscription plan billing interval. Can be daily, weekly, monthly, or yearly.
Possible enum values:
billing_schedule.interval_count
intrequiredMultiplier for billing interval. For example, to make the billing cycle once every two weeks, set interval=weekly and interval_count=2.
billing_schedule.limit
intSpecifies 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.
billing_schedule.trial_days
intNumber of days offered as a free trial on the subscription plan before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued.
attributes
objectAn object containing custom attribute key/value pairs.
bundle
booleanIndicates whether the product is a bundle of other products.
bundle_items
array of objectList of products sold as a bundle. Applicable only when bundle=true.
id
objectIdautoUnique identifier for the bundle item.
product_id
objectIdrequiredID of the bundled product.
product
ProductExpandable link to the bundled product.
quantity
intQuantity of the bundled product. Defaults to 1.
variant_id
objectIdID of the bundled variant, if applicable.
variant
Product variantExpandable link to the bundled product variant, if applicable.
product_name
stringThis field is a copy of the item's product.name.
category
CategoryExpandable link to the primary category.
category_id
objectIdPrimary category, commonly used as a navigation anchor.
categories
CategoryExpandable link to all related product categories.
category_index
objectIndex of categories used for fast lookup operations.
category_index.id
array of child_scalarList of related product category IDs.
category_index.sort
objectIndex of category IDs and their respective sort positions.
code
stringUnique code to identify the gift card product.
cost
currencyCost of goods (COGS) used to calculate gross margins.
cross_sells
array of objectList of products to display as cross-sells on a shopping cart page.
id
objectIdautoUnique identifier for the cross-sell object.
product_id
objectIdrequiredID of the cross-sell product.
product
ProductExpandable link to the cross-sell product.
discount_type
enumType of discount to apply, either fixed or percent.
discount_amount
currencyDiscount to apply as a fixed amount. Applicable only when discount_type=fixed.
discount_percent
floatDiscount to apply as a percentage. Applicable only when discount_type=percent.
currency
stringThree-letter ISO currency code in uppercase. Defaults to your store's base currency.
customizable
booleanIndicates whether the product has custom options enabled.
date_created
dateautoDate and time the product was created.
date_updated
dateautoDate and time the product was last updated.
delivery
enumautoMethod 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.
description
stringA long-form description of the product. May contain HTML or other markup languages.
discontinued
booleanIndicates whether the product has been discontinued.
images
array of objectList of images depicting the bundle.
id
objectIdautoUnique identifier for the image.
caption
stringA brief description of the image, intended for display as a caption or alt text.
file
objectAn object representing the image's source file.
file.id
objectIdUnique identifier for the file.
file.filename
stringOptional file name.
file.data
filedataA reference to the raw file data.
file.content_type
stringMIME content type of the file.
file.date_uploaded
dateDate the file was uploaded.
file.height
intImage height in pixels, if applicable.
file.length
intSize of the file in bytes.
file.metadata
objectA set of arbitrary data that is typically used to store custom values.
file.md5
stringAn MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
file.private
booleanIndicates whether the file is private.
file.url
stringA public URL to reference the file. Updated automatically if file content changes.
file.width
intImage width in pixels, if applicable.
meta_title
stringPage title used to override product name in storefronts.
meta_keywords
stringPage keywords used for search engine optimization purposes.
meta_description
stringPage description used for search engine optimization purposes.
options
array of objectOptions 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.
id
objectIdautoUnique identifier for the object.
name
stringrequiredHuman-friendly name of the option.
input_hint
stringSome brief hint text to help the user understand this option.
input_type
enumType 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.
parent_id
objectIdSpecifies another option ID that affects visibility of this option. The option will only appear when one of the parent_value_ids is selected.
parent_value_ids
array of child_scalarIDs of parent option values that will make the option appear if selected.
price
currencyExtra 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.
required
booleanIndicates whether the option requires a value when the product is added to a cart.
subscription
booleanIndicates whether the option specifies the billing interval of a subscription plan.
values
array of objectList of possible values for this option.
id
objectIdautoUnique identifier for the object.
name
stringrequiredHuman-friendly name of the option value.
color
stringName of the product color.
description
stringA brief description of the option value, intended for displaying to customers.
price
currencyExtra price added to the product's price/sale_price if the option value is selected. Overrides option price.
shipment_weight
floatExtra 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.
subscription_interval
enumWhen product type=subscription, this is the billing interval used when this option value is selected. Can be monthly, yearly, weekly, or daily.
Possible enum values:
subscription_interval_count
intWhen 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.
subscription_trial_days
intWhen product type=subscription, refers to a number of days offered as a trial before an invoice is issued.
image
objectImage depicting the product.
image.id
objectIdUnique identifier for the object.
image.data
filedataA reference to the raw file data.
image.date_uploaded
dateDate the file was uploaded.
image.length
intSize of the file in bytes.
image.md5
stringAn MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
image.filename
stringOptional file name.
image.content_type
stringMIME content type of the file.
image.metadata
objectArbitrary data
image.private
booleanimage.url
stringimage.width
intimage.height
intimages
array of objectid
objectIdautocaption
stringfile
objectfile.id
objectIdfile.date_uploaded
datefile.length
intfile.md5
stringfile.filename
stringfile.content_type
stringfile.metadata
objectfile.data
filedatafile.private
booleanfile.url
stringfile.width
intfile.height
intattribute_id
stringUnique identifier for the attribute.
description
stringDescription for the product options.
active
booleanIndicates the options are active.
input_multi
booleanIndicates there are multiple selections for options.
variant
booleanIndicates the option is a variant.
orig_price
currencyReflects the non-sale price of the product
price
currencyList price used when sale=false or sale_price is not defined. This value is intended for use via the frontend. See the purchase_options array to manage a product's price.
prices
array of pricePrice rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
price.price
currencyrequiredPrice applied when conditions are met.
price.account_group
stringCustomer account group as a condition to apply price.
price.quantity_max
intMaximum quantity as a condition to apply price.
price.quantity_min
intMinimum quantity as a condition to apply price.
quantity_min
intMinimum quantity of the product that can be sold at once.
quantity_inc
intSpecifies a quantify multiple the product must be sold in.
related_product_ids
array of child_scalarArray of related product IDs.
sale
booleanIndicates 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
currencySale price used to override list price when sale=true.
shipment_package_quantity
floatIf specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package.
subscription_interval
enumThe default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly, or daily.
subscription_interval_count
intMultiplier when combined with subscription_interval. For example, to make a subscription bill every two weeks, set subscription_interval=weekly and subscription_interval_count=2.
subscription_trial_days
intNumber 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.
sku
stringrequiredStock keeping unit (SKU) used to track inventory in a warehouse.
slug
stringrequiredLowercase, 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.
stock
array of StockExpandable list of stock adjustments for the product.
stock_backorder
booleanIndicates whether the product can be backordered if out of stock.
stock_level
intQuantity of the product currently in stock (including all variants), based on the sum of the stock entries.
stock_preorder
booleanIndicates whether the product can be purchased as a preorder.
stock_purchasable
booleanIndicates whether the product's stock is purchasable.
stock_status
enumautoString 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.
stock_tracking
booleanIndicates whether the product has stock tracking enabled.
summary
stringA brief product summary.
tags
array of child_scalarArray of searchable tags to aid in search discoverability.
tax_class
stringIndicates the tax class for the product.
tax_code
stringProduct tax code for tracking with Avalara, TaxJar, etc.
type
stringImplies 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.
up_sells
array of objectList of products to display as up-sells on a product detail page.
id
objectIdautoUnique identifier for the up-sell.
product_id
objectIdrequiredID of the up-sell product.
product
ProductExpandable link to the up-sell product.
variable
booleanIndicates whether the product has variant generation enabled.
variants
array of VariantsExpandable list of variants representing unique variations of the product. Each variant is a combination of one or more options. For example, Size and Color.
virtual
booleanIndicates whether the product is virtual.
With products now in your store, the next step is to set up their purchase options. These are ways for your customers to purchase particular products—be it through a one-time purchase or through a recurring subscription plan. Each product supports more than one type of purchase option, so you can sell a product in multiple ways.