# Product modeling Source: https://developers.swell.is/guides/core-concepts/product-modeling Swell products have four basic product types: `physical`, `digital`, `bundle`, and `gift card`. Each type has a distinct way of operating within the API. Each type has unique dashboard fields and settings. You can use any of the default product types to build your own custom product types. #### Physical 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. #### Digital 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. Digital products have no shipping details, but they can have inventory tracking enabled. #### Bundle 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 #### Gift card 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. > **Tip:** When gift card products are sold, a gift card code is created and sent to a recipient via email. Once fulfilled, gift card codes act as a payment method in a card, and can also be converted to a customer's account as credit. ### Basic product information #### Name 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. #### Attributes 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. #### Categories 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. #### SKU Designate the product `SKU` (stock keeping unit) for inventory tracking purposes. ### Options and variants #### Options 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`. **See relevant fields** **Fields** - `options` (array of object): Options that allow for variations of the base product. If the option is part of a variant or `required=true`, an option value must be set for the product to be added to a cart. - `id` (objectId, auto): Unique identifier for the object. - `name` (string, required): Human-friendly name of the option. - `input_hint` (string): Some brief hint text to help the user understand this option. - `input_type` (enum): Type of user input to display for this option in a storefront. The *select* type is ideal for dropdown or radio selections, *toggle* can be used either to show another option or as a price modifier, and *text* fields can capture user input like a message. - `parent_id` (objectId): Specifies 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_scalar): IDs of parent option values that will make the option appear if selected. - `price` (currency): Extra price for the option, added to the product's `price`/`sale_price`. If the option is part of a variant, the variant's `price`/`sale_price` will override this value. - `required` (boolean): Indicates whether the option requires a value when the product is added to a cart. Default: `{"$formula":"if(input_type == 'toggle', false, true)"}`. - `subscription` (boolean): Indicates whether the option specifies the billing interval of a subscription plan. - `values` (array of object): List of possible values for this option. - `id` (objectId, auto): Unique identifier for the object. - `name` (string, required): Human-friendly name of the option value. - `color` (string): Name of the product color. - `description` (string): A brief description of the option value, intended for displaying to customers. - `price` (currency): Extra price added to the product's `price`/`sale_price` if the option value is selected. Overrides option `price`. - `shipment_weight` (float): Extra weight added to the product's `shipment_weight` if the option value is selected. The unit should match the store's default as configured in general settings. - `subscription_interval` (enum): When product `type=subscription`, this is the billing interval used when this option value is selected. Can be `monthly`, `yearly`, `weekly`, or `daily`. Possible values: `monthly`, `daily`, `weekly`, `yearly`. - `subscription_interval_count` (int): When product `type=subscription`, this number multiplies `subscription_interval` to determine the billing frequency when this option is selected. For example, to make a subscription bill every two weeks, set `subscription_interval=weekly` and `subscription_interval_count=2`. - `subscription_trial_days` (int): When product `type=subscription`, refers to a number of days offered as a trial before an invoice is issued. - `image` (object): Image depicting the product. - `id` (objectId): Unique identifier for the object. - `data` (filedata): A reference to the raw file data. - `date_uploaded` (date): Date the file was uploaded. - `length` (int): Size of the file in bytes. - `md5` (string): An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes. - `filename` (string): Optional file name. - `content_type` (string): MIME content type of the file. - `metadata` (object): Arbitrary data - `private` (boolean) - `url` (string) - `width` (int) - `height` (int) - `attribute_id` (string): Unique identifier for the attribute. - `active` (boolean): Indicates the options are active. Default: `true`. - `input_multi` (boolean): Indicates there are multiple selections for options. - `id` (objectId): Unique identifier for the product. - `name` (string, required): Human-friendly name of the product. - `active` (boolean): Indicates whether the product is active and available in the storefront. Default: `false`. - `purchase_options` (object): Configuration of one or more purchase options for the product. Can be `standard` for one-time purchases or `subscription` for a subscription plan. Products can support both purchase options simultaneously. - `standard` (object): Designates purchase option as a one-time purchase. - `id` (objectId): ID of the purchase option. - `name` (string, required): The name of the purchase option. - `description` (string): A long-form description of the product. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `price` (currency): List price used when `sale=false` or `sale_price` is not defined. - `sale` (boolean): Indicates whether the product option is on sale. If `true`, the `sale_price` will be used by default when the product is added to a cart. - `sale_price` (currency): Sale price used by default when `sale=true`, overriding `price`. Overrides product sale price. - `prices` (array of object): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `account_groups` (array of string): Array of account groups that are eligible to access the purchase option within the storefront. - `subscription` (object): Designates purchase option for a subscription plan. - `id` (objectId, auto): ID of the subscription plan purchase option. - `name` (string, required): Name of the subscription plan purchase option. - `description` (string): A long-form description of the purchase option. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `account_groups` (array of string): Array of `account_group` names for which the purchase option is available. - `plans` (array of plans): Array defining subscription plans and their respective configurations. - `id` (objectId): ID of the purchase option subscription plan. - `name` (string, required): Name of the subscription plan. - `description` (string): A long-form description of the subscription plan. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the subscription plan is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `price` (currency): List price used when `sale=false` or `sale_price` is not defined. - `prices` (array of object): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `billing_schedule` (object, required): Determines the billing schedule for the subscription plan. - `interval` (enum): Subscription plan billing interval. Can be `daily`, `weekly`, `monthly`, or `yearly`. Possible values: `daily`, `weekly`, `monthly`, `yearly`. Default: `monthly`. - `interval_count` (int, required): Multiplier for billing interval. For example, to make the billing cycle once every two weeks, set `interval=weekly` and `interval_count=2`. Default: `1`. - `limit` (int): Specifies a limit to the number of billing cycles for the subscription plan. For example, `limit=10` would stop billing the customer after the tenth billing cycle. Default: `∞`. - `trial_days` (int): Number 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` (object): An object containing custom attribute values, keyed by each attribute's `id`. A value can be a single value or an array. - `bundle` (boolean): Indicates whether the product is a bundle of other products. - `bundle_items` (array of object): List of products sold as a bundle. Applicable only when `bundle=true`. - `id` (objectId, auto): Unique identifier for the bundle item. - `product_id` (objectId, required): ID of the bundled product. - `product` (Product): Expandable link to the bundled product. - `quantity` (int): Quantity of the bundled product. Defaults to 1. Default: `1`. - `variant_id` (objectId): ID of the bundled variant, if applicable. - `variant` (Product variant): Expandable link to the bundled product variant, if applicable. - `product_name` (string): This field is a copy of the item's `product.name`. Default: `{"$formula": "if(product_id, product.name, null)"}`. - `category` (Category): Expandable link to the primary category. - `category_id` (objectId): Primary category, commonly used as a navigation anchor. - `categories` (Category): Expandable link to all related product categories. - `category_index` (object): Index of categories used for fast lookup operations. - `id` (array of child_scalar): List of related product category IDs. - `sort` (object): Index of category IDs and their respective sort positions. - `code` (string): Unique code to identify the gift card product. - `cost` (currency): Cost of goods (COGS) used to calculate gross margins. - `cross_sells` (array of object): List of products to display as cross-sells on a shopping cart page. - `id` (objectId, auto): Unique identifier for the cross-sell object. - `product_id` (objectId, required): ID of the cross-sell product. - `product` (Product): Expandable link to the cross-sell product. - `discount_type` (enum): Type of discount to apply, either `fixed` or `percent`. - `discount_amount` (currency): Discount to apply as a fixed amount. Applicable only when `discount_type=fixed`. - `discount_percent` (float): Discount to apply as a percentage. Applicable only when `discount_type=percent`. - `currency` (string): Three-letter ISO currency code in uppercase. Defaults to your store's base currency. - `customizable` (boolean): Indicates whether the product has custom options enabled. - `date_created` (date, auto): Date and time the product was created. - `date_updated` (date, auto): Date and time the product was last updated. - `delivery` (enum, auto): Method of fulfillment automatically assigned based on `type`: - `shipment` means the product will be physically shipped to a customer. - `subscription` means the product will be fulfilled as a [subscription ](https://developers.swell.is/backend-api/subscriptions/the-subscription-model)when an order is placed. `giftcard` delivery means the product will be fulfilled as a [gift card](https://developers.swell.is/backend-api/pages/the-pages-model) 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` (string): A long-form description of the product. May contain HTML or other markup languages. - `discontinued` (boolean): Indicates whether the product has been discontinued. - `images` (array of object): List of images depicting the bundle. - `id` (objectId, auto): Unique identifier for the image. - `caption` (string): A brief description of the image, intended for display as a caption or alt text. - `file` (object): An object representing the image's source file. - `id` (objectId): Unique identifier for the file. - `filename` (string): Optional file name. - `data` (filedata): A reference to the raw file data. - `content_type` (string): MIME content type of the file. - `date_uploaded` (date): Date the file was uploaded. - `height` (int): Image height in pixels, if applicable. - `length` (int): Size of the file in bytes. - `metadata` (object): A set of arbitrary data that is typically used to store custom values. - `md5` (string): An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes. - `private` (boolean): Indicates whether the file is private. - `url` (string): A public URL to reference the file. Updated automatically if file content changes. - `width` (int): Image width in pixels, if applicable. - `meta_title` (string): Page title used to override product name in storefronts. - `meta_keywords` (string): Page keywords used for search engine optimization purposes. - `meta_description` (string): Page description used for search engine optimization purposes. - `orig_price` (currency): Reflects the non-sale price of the product - `price` (currency): List 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. Default: `0`. - `prices` (array of price): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity of the product that can be sold at once. - `quantity_inc` (int): Specifies a quantify multiple the product must be sold in. - `related_product_ids` (array of child_scalar): Array of related product IDs. - `sale` (boolean): Indicates whether the product is on sale. If `true`, the `sale_price` will be used by default when the product is added to a cart. - `sale_price` (currency): Sale price used to override list price when `sale=true`. - `shipment_dimensions` (object): Product dimensions when packed for shipping. Typically used by third-party carriers in box packing algorithms to optimize shipping costs. - `length` (float, required): Length of the product in `unit`. - `width` (float, required): Width of the product in `unit`. - `height` (float, required): Height of the product in `unit`. - `unit` (enum, required): Either `in`(inches) or `cm`(centimeters). Default: `"in"`. - `shipment_location` (string): ID 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` (float): If specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package. - `shipment_prices` (array of object): Product shipping price rules to override default shipping rules. - `service` (string, required): Shipping service required for this rule to apply. - `account_group` (string): Customer group required for this rule to apply. - `country` (string): Shipping country required for this rule to apply. - `fee_amount` (currency): Fixed amount to add when rule is applied. Only applicable when `fee_type=fixed`. - `fee_percent` (float): Percentage of the shipping price to add when rule is applied. Only applicable when `fee_type=percent`. - `fee_type` (enum): Type of fee to apply in addition to `price`, either `fixed` or `percent`. - `package_quantity` (int): Maximum package quantity when rule is applied. - `price` (currency): Shipping price when rule is applied. - `state` (string): Shipping state required for this rule to apply. - `total_max` (currency): Maximum order subtotal for this rule to apply. - `total_min` (currency): Minimum order subtotal for this rule to apply. - `weight_max` (float): Maximum order item weight for this rule to apply. - `weight_min` (float): Minimum order item weight for this rule to apply. - `zip` (string): Shipping zip/postal code required for this rule to apply. - `shipment_weight` (float): If specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg—depending on the store's default weight unit. - `subscription_interval` (enum): The default billing interval when this product is used as a subscription plan. Can be `monthly`, `yearly`, `weekly`, or `daily`. - `subscription_interval_count` (int): Multiplier when combined with `subscription_interval`. For example, to make a subscription bill every two weeks, set `subscription_interval=weekly` and `subscription_interval_count=2`. - `subscription_trial_days` (int): Number of days offered as a free trial before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued. - `sku` (string): Stock keeping unit (SKU) used to track inventory in a warehouse. - `slug` (string, required): Lowercase, hyphenated identifier typically used in URLs. When creating a product, a `slug` will be generated automatically from the `name`. Maximum length of 1,000 characters. Default: `{"$formula":"slug(name)"}`. - `stock` (array of Stock): Expandable list of stock adjustments for the product. - `stock_backorder` (boolean): Indicates whether the product can be backordered if out of stock. - `stock_level` (int, auto): Quantity of the product currently in stock (including all variants), based on the sum of the stock entries. Includes positive quantities, excluding variants that have negative stock values. - `stock_level_in_locations` (int): Quantity of the product in stock across inventory locations, if the product has no variants. - `stock_level_min` (int, auto): Minimum stock value including all variants. May represent negative variant stock levels. - `stock_level_total` (int, auto): Sum total of all product stock values. - `stock_locations` (object): Stock distributed over inventory locations, if multi-location inventory is enabled. - `available_locations` (array of location): List of custom inventory locations for this product. - `id` (string): Location identifier. - `name` (string): Location name. - `stock_preorder` (boolean): Indicates whether the product can be purchased as a preorder. - `stock_purchasable` (boolean): Indicates whether the product's stock is purchasable. - `stock_status` (enum, auto): String indicating the product's stock status for the purpose of ordering. When `stock_purchasable=true`, an order can be placed for this product regardless of current stock status. Otherwise an order submission will be blocked unless stock status is `available`, `preorder`, or `backorder`. - `stock_tracking` (boolean): Indicates whether the product has stock tracking enabled. - `summary` (string): A brief product summary. - `tags` (array of child_scalar): Array of searchable tags to aid in search discoverability. - `tax_class` (string): Indicates the tax class for the product. - `tax_code` (string): Product tax code for tracking with Avalara, TaxJar, etc. - `theme_template` (string): ID of an alternate theme template used to render this product in a storefront, if applicable. - `type` (string): Implies the ordering and fulfillment options available for the product. Can be `standard`, `subscription`, `bundle`, or `giftcard`. A `standard` product is a physical item that will be shipped to a customer. Default: `"standard"`. - `up_sells` (array of object): List of products to display as up-sells on a product detail page. - `id` (objectId, auto): Unique identifier for the up-sell. - `product_id` (objectId, required): ID of the up-sell product. - `product` (Product): Expandable link to the up-sell product. - `variable` (boolean): Indicates whether the product has variant generation enabled. - `variants` (array of Variants): Expandable list of variants representing unique variations of the product. Each variant is a combination of one or more `options`. For example, Size and Color. - `virtual` (boolean): Indicates whether the product is virtual. #### Variants 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. **See relevant fields** **Fields** - `variants` (array of Variants): Expandable list of variants representing unique variations of the product. Each variant is a combination of one or more `options`. For example, Size and Color. - `id` (objectId): Unique identifier for the product. - `name` (string, required): Human-friendly name of the product. - `active` (boolean): Indicates whether the product is active and available in the storefront. Default: `false`. - `purchase_options` (object): Configuration of one or more purchase options for the product. Can be `standard` for one-time purchases or `subscription` for a subscription plan. Products can support both purchase options simultaneously. - `standard` (object): Designates purchase option as a one-time purchase. - `id` (objectId): ID of the purchase option. - `name` (string, required): The name of the purchase option. - `description` (string): A long-form description of the product. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `price` (currency): List price used when `sale=false` or `sale_price` is not defined. - `sale` (boolean): Indicates whether the product option is on sale. If `true`, the `sale_price` will be used by default when the product is added to a cart. - `sale_price` (currency): Sale price used by default when `sale=true`, overriding `price`. Overrides product sale price. - `prices` (array of object): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `account_groups` (array of string): Array of account groups that are eligible to access the purchase option within the storefront. - `subscription` (object): Designates purchase option for a subscription plan. - `id` (objectId, auto): ID of the subscription plan purchase option. - `name` (string, required): Name of the subscription plan purchase option. - `description` (string): A long-form description of the purchase option. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `account_groups` (array of string): Array of `account_group` names for which the purchase option is available. - `plans` (array of plans): Array defining subscription plans and their respective configurations. - `id` (objectId): ID of the purchase option subscription plan. - `name` (string, required): Name of the subscription plan. - `description` (string): A long-form description of the subscription plan. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the subscription plan is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `price` (currency): List price used when `sale=false` or `sale_price` is not defined. - `prices` (array of object): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `billing_schedule` (object, required): Determines the billing schedule for the subscription plan. - `interval` (enum): Subscription plan billing interval. Can be `daily`, `weekly`, `monthly`, or `yearly`. Possible values: `daily`, `weekly`, `monthly`, `yearly`. Default: `monthly`. - `interval_count` (int, required): Multiplier for billing interval. For example, to make the billing cycle once every two weeks, set `interval=weekly` and `interval_count=2`. Default: `1`. - `limit` (int): Specifies a limit to the number of billing cycles for the subscription plan. For example, `limit=10` would stop billing the customer after the tenth billing cycle. Default: `∞`. - `trial_days` (int): Number 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` (object): An object containing custom attribute values, keyed by each attribute's `id`. A value can be a single value or an array. - `bundle` (boolean): Indicates whether the product is a bundle of other products. - `bundle_items` (array of object): List of products sold as a bundle. Applicable only when `bundle=true`. - `id` (objectId, auto): Unique identifier for the bundle item. - `product_id` (objectId, required): ID of the bundled product. - `product` (Product): Expandable link to the bundled product. - `quantity` (int): Quantity of the bundled product. Defaults to 1. Default: `1`. - `variant_id` (objectId): ID of the bundled variant, if applicable. - `variant` (Product variant): Expandable link to the bundled product variant, if applicable. - `product_name` (string): This field is a copy of the item's `product.name`. Default: `{"$formula": "if(product_id, product.name, null)"}`. - `category` (Category): Expandable link to the primary category. - `category_id` (objectId): Primary category, commonly used as a navigation anchor. - `categories` (Category): Expandable link to all related product categories. - `category_index` (object): Index of categories used for fast lookup operations. - `id` (array of child_scalar): List of related product category IDs. - `sort` (object): Index of category IDs and their respective sort positions. - `code` (string): Unique code to identify the gift card product. - `cost` (currency): Cost of goods (COGS) used to calculate gross margins. - `cross_sells` (array of object): List of products to display as cross-sells on a shopping cart page. - `id` (objectId, auto): Unique identifier for the cross-sell object. - `product_id` (objectId, required): ID of the cross-sell product. - `product` (Product): Expandable link to the cross-sell product. - `discount_type` (enum): Type of discount to apply, either `fixed` or `percent`. - `discount_amount` (currency): Discount to apply as a fixed amount. Applicable only when `discount_type=fixed`. - `discount_percent` (float): Discount to apply as a percentage. Applicable only when `discount_type=percent`. - `currency` (string): Three-letter ISO currency code in uppercase. Defaults to your store's base currency. - `customizable` (boolean): Indicates whether the product has custom options enabled. - `date_created` (date, auto): Date and time the product was created. - `date_updated` (date, auto): Date and time the product was last updated. - `delivery` (enum, auto): Method of fulfillment automatically assigned based on `type`: - `shipment` means the product will be physically shipped to a customer. - `subscription` means the product will be fulfilled as a [subscription ](https://developers.swell.is/backend-api/subscriptions/the-subscription-model)when an order is placed. `giftcard` delivery means the product will be fulfilled as a [gift card](https://developers.swell.is/backend-api/pages/the-pages-model) 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` (string): A long-form description of the product. May contain HTML or other markup languages. - `discontinued` (boolean): Indicates whether the product has been discontinued. - `images` (array of object): List of images depicting the bundle. - `id` (objectId, auto): Unique identifier for the image. - `caption` (string): A brief description of the image, intended for display as a caption or alt text. - `file` (object): An object representing the image's source file. - `id` (objectId): Unique identifier for the file. - `filename` (string): Optional file name. - `data` (filedata): A reference to the raw file data. - `content_type` (string): MIME content type of the file. - `date_uploaded` (date): Date the file was uploaded. - `height` (int): Image height in pixels, if applicable. - `length` (int): Size of the file in bytes. - `metadata` (object): A set of arbitrary data that is typically used to store custom values. - `md5` (string): An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes. - `private` (boolean): Indicates whether the file is private. - `url` (string): A public URL to reference the file. Updated automatically if file content changes. - `width` (int): Image width in pixels, if applicable. - `meta_title` (string): Page title used to override product name in storefronts. - `meta_keywords` (string): Page keywords used for search engine optimization purposes. - `meta_description` (string): Page description used for search engine optimization purposes. - `options` (array of object): Options that allow for variations of the base product. If the option is part of a variant or `required=true`, an option value must be set for the product to be added to a cart. - `id` (objectId, auto): Unique identifier for the object. - `name` (string, required): Human-friendly name of the option. - `input_hint` (string): Some brief hint text to help the user understand this option. - `input_type` (enum): Type of user input to display for this option in a storefront. The *select* type is ideal for dropdown or radio selections, *toggle* can be used either to show another option or as a price modifier, and *text* fields can capture user input like a message. - `parent_id` (objectId): Specifies 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_scalar): IDs of parent option values that will make the option appear if selected. - `price` (currency): Extra price for the option, added to the product's `price`/`sale_price`. If the option is part of a variant, the variant's `price`/`sale_price` will override this value. - `required` (boolean): Indicates whether the option requires a value when the product is added to a cart. Default: `{"$formula":"if(input_type == 'toggle', false, true)"}`. - `subscription` (boolean): Indicates whether the option specifies the billing interval of a subscription plan. - `values` (array of object): List of possible values for this option. - `id` (objectId, auto): Unique identifier for the object. - `name` (string, required): Human-friendly name of the option value. - `color` (string): Name of the product color. - `description` (string): A brief description of the option value, intended for displaying to customers. - `price` (currency): Extra price added to the product's `price`/`sale_price` if the option value is selected. Overrides option `price`. - `shipment_weight` (float): Extra weight added to the product's `shipment_weight` if the option value is selected. The unit should match the store's default as configured in general settings. - `subscription_interval` (enum): When product `type=subscription`, this is the billing interval used when this option value is selected. Can be `monthly`, `yearly`, `weekly`, or `daily`. Possible values: `monthly`, `daily`, `weekly`, `yearly`. - `subscription_interval_count` (int): When product `type=subscription`, this number multiplies `subscription_interval` to determine the billing frequency when this option is selected. For example, to make a subscription bill every two weeks, set `subscription_interval=weekly` and `subscription_interval_count=2`. - `subscription_trial_days` (int): When product `type=subscription`, refers to a number of days offered as a trial before an invoice is issued. - `image` (object): Image depicting the product. - `id` (objectId): Unique identifier for the object. - `data` (filedata): A reference to the raw file data. - `date_uploaded` (date): Date the file was uploaded. - `length` (int): Size of the file in bytes. - `md5` (string): An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes. - `filename` (string): Optional file name. - `content_type` (string): MIME content type of the file. - `metadata` (object): Arbitrary data - `private` (boolean) - `url` (string) - `width` (int) - `height` (int) - `attribute_id` (string): Unique identifier for the attribute. - `active` (boolean): Indicates the options are active. Default: `true`. - `input_multi` (boolean): Indicates there are multiple selections for options. - `orig_price` (currency): Reflects the non-sale price of the product - `price` (currency): List 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. Default: `0`. - `prices` (array of price): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity of the product that can be sold at once. - `quantity_inc` (int): Specifies a quantify multiple the product must be sold in. - `related_product_ids` (array of child_scalar): Array of related product IDs. - `sale` (boolean): Indicates whether the product is on sale. If `true`, the `sale_price` will be used by default when the product is added to a cart. - `sale_price` (currency): Sale price used to override list price when `sale=true`. - `shipment_dimensions` (object): Product dimensions when packed for shipping. Typically used by third-party carriers in box packing algorithms to optimize shipping costs. - `length` (float, required): Length of the product in `unit`. - `width` (float, required): Width of the product in `unit`. - `height` (float, required): Height of the product in `unit`. - `unit` (enum, required): Either `in`(inches) or `cm`(centimeters). Default: `"in"`. - `shipment_location` (string): ID 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` (float): If specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package. - `shipment_prices` (array of object): Product shipping price rules to override default shipping rules. - `service` (string, required): Shipping service required for this rule to apply. - `account_group` (string): Customer group required for this rule to apply. - `country` (string): Shipping country required for this rule to apply. - `fee_amount` (currency): Fixed amount to add when rule is applied. Only applicable when `fee_type=fixed`. - `fee_percent` (float): Percentage of the shipping price to add when rule is applied. Only applicable when `fee_type=percent`. - `fee_type` (enum): Type of fee to apply in addition to `price`, either `fixed` or `percent`. - `package_quantity` (int): Maximum package quantity when rule is applied. - `price` (currency): Shipping price when rule is applied. - `state` (string): Shipping state required for this rule to apply. - `total_max` (currency): Maximum order subtotal for this rule to apply. - `total_min` (currency): Minimum order subtotal for this rule to apply. - `weight_max` (float): Maximum order item weight for this rule to apply. - `weight_min` (float): Minimum order item weight for this rule to apply. - `zip` (string): Shipping zip/postal code required for this rule to apply. - `shipment_weight` (float): If specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg—depending on the store's default weight unit. - `subscription_interval` (enum): The default billing interval when this product is used as a subscription plan. Can be `monthly`, `yearly`, `weekly`, or `daily`. - `subscription_interval_count` (int): Multiplier when combined with `subscription_interval`. For example, to make a subscription bill every two weeks, set `subscription_interval=weekly` and `subscription_interval_count=2`. - `subscription_trial_days` (int): Number of days offered as a free trial before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued. - `sku` (string): Stock keeping unit (SKU) used to track inventory in a warehouse. - `slug` (string, required): Lowercase, hyphenated identifier typically used in URLs. When creating a product, a `slug` will be generated automatically from the `name`. Maximum length of 1,000 characters. Default: `{"$formula":"slug(name)"}`. - `stock` (array of Stock): Expandable list of stock adjustments for the product. - `stock_backorder` (boolean): Indicates whether the product can be backordered if out of stock. - `stock_level` (int, auto): Quantity of the product currently in stock (including all variants), based on the sum of the stock entries. Includes positive quantities, excluding variants that have negative stock values. - `stock_level_in_locations` (int): Quantity of the product in stock across inventory locations, if the product has no variants. - `stock_level_min` (int, auto): Minimum stock value including all variants. May represent negative variant stock levels. - `stock_level_total` (int, auto): Sum total of all product stock values. - `stock_locations` (object): Stock distributed over inventory locations, if multi-location inventory is enabled. - `available_locations` (array of location): List of custom inventory locations for this product. - `id` (string): Location identifier. - `name` (string): Location name. - `stock_preorder` (boolean): Indicates whether the product can be purchased as a preorder. - `stock_purchasable` (boolean): Indicates whether the product's stock is purchasable. - `stock_status` (enum, auto): String indicating the product's stock status for the purpose of ordering. When `stock_purchasable=true`, an order can be placed for this product regardless of current stock status. Otherwise an order submission will be blocked unless stock status is `available`, `preorder`, or `backorder`. - `stock_tracking` (boolean): Indicates whether the product has stock tracking enabled. - `summary` (string): A brief product summary. - `tags` (array of child_scalar): Array of searchable tags to aid in search discoverability. - `tax_class` (string): Indicates the tax class for the product. - `tax_code` (string): Product tax code for tracking with Avalara, TaxJar, etc. - `theme_template` (string): ID of an alternate theme template used to render this product in a storefront, if applicable. - `type` (string): Implies the ordering and fulfillment options available for the product. Can be `standard`, `subscription`, `bundle`, or `giftcard`. A `standard` product is a physical item that will be shipped to a customer. Default: `"standard"`. - `up_sells` (array of object): List of products to display as up-sells on a product detail page. - `id` (objectId, auto): Unique identifier for the up-sell. - `product_id` (objectId, required): ID of the up-sell product. - `product` (Product): Expandable link to the up-sell product. - `variable` (boolean): Indicates whether the product has variant generation enabled. - `virtual` (boolean): Indicates whether the product is virtual. ### Pricing 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`. **See relevant fields** **Fields** - `price` (currency): List 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. Default: `0`. - `sale` (boolean): Indicates whether the product is on sale. If `true`, the `sale_price` will be used by default when the product is added to a cart. - `sale_price` (currency): Sale price used to override list price when `sale=true`. - `id` (objectId): Unique identifier for the product. - `name` (string, required): Human-friendly name of the product. - `active` (boolean): Indicates whether the product is active and available in the storefront. Default: `false`. - `purchase_options` (object): Configuration of one or more purchase options for the product. Can be `standard` for one-time purchases or `subscription` for a subscription plan. Products can support both purchase options simultaneously. - `standard` (object): Designates purchase option as a one-time purchase. - `id` (objectId): ID of the purchase option. - `name` (string, required): The name of the purchase option. - `description` (string): A long-form description of the product. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `price` (currency): List price used when `sale=false` or `sale_price` is not defined. - `sale` (boolean): Indicates whether the product option is on sale. If `true`, the `sale_price` will be used by default when the product is added to a cart. - `sale_price` (currency): Sale price used by default when `sale=true`, overriding `price`. Overrides product sale price. - `prices` (array of object): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `account_groups` (array of string): Array of account groups that are eligible to access the purchase option within the storefront. - `subscription` (object): Designates purchase option for a subscription plan. - `id` (objectId, auto): ID of the subscription plan purchase option. - `name` (string, required): Name of the subscription plan purchase option. - `description` (string): A long-form description of the purchase option. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `account_groups` (array of string): Array of `account_group` names for which the purchase option is available. - `plans` (array of plans): Array defining subscription plans and their respective configurations. - `id` (objectId): ID of the purchase option subscription plan. - `name` (string, required): Name of the subscription plan. - `description` (string): A long-form description of the subscription plan. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the subscription plan is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `price` (currency): List price used when `sale=false` or `sale_price` is not defined. - `prices` (array of object): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `billing_schedule` (object, required): Determines the billing schedule for the subscription plan. - `interval` (enum): Subscription plan billing interval. Can be `daily`, `weekly`, `monthly`, or `yearly`. Possible values: `daily`, `weekly`, `monthly`, `yearly`. Default: `monthly`. - `interval_count` (int, required): Multiplier for billing interval. For example, to make the billing cycle once every two weeks, set `interval=weekly` and `interval_count=2`. Default: `1`. - `limit` (int): Specifies a limit to the number of billing cycles for the subscription plan. For example, `limit=10` would stop billing the customer after the tenth billing cycle. Default: `∞`. - `trial_days` (int): Number 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` (object): An object containing custom attribute values, keyed by each attribute's `id`. A value can be a single value or an array. - `bundle` (boolean): Indicates whether the product is a bundle of other products. - `bundle_items` (array of object): List of products sold as a bundle. Applicable only when `bundle=true`. - `id` (objectId, auto): Unique identifier for the bundle item. - `product_id` (objectId, required): ID of the bundled product. - `product` (Product): Expandable link to the bundled product. - `quantity` (int): Quantity of the bundled product. Defaults to 1. Default: `1`. - `variant_id` (objectId): ID of the bundled variant, if applicable. - `variant` (Product variant): Expandable link to the bundled product variant, if applicable. - `product_name` (string): This field is a copy of the item's `product.name`. Default: `{"$formula": "if(product_id, product.name, null)"}`. - `category` (Category): Expandable link to the primary category. - `category_id` (objectId): Primary category, commonly used as a navigation anchor. - `categories` (Category): Expandable link to all related product categories. - `category_index` (object): Index of categories used for fast lookup operations. - `id` (array of child_scalar): List of related product category IDs. - `sort` (object): Index of category IDs and their respective sort positions. - `code` (string): Unique code to identify the gift card product. - `cost` (currency): Cost of goods (COGS) used to calculate gross margins. - `cross_sells` (array of object): List of products to display as cross-sells on a shopping cart page. - `id` (objectId, auto): Unique identifier for the cross-sell object. - `product_id` (objectId, required): ID of the cross-sell product. - `product` (Product): Expandable link to the cross-sell product. - `discount_type` (enum): Type of discount to apply, either `fixed` or `percent`. - `discount_amount` (currency): Discount to apply as a fixed amount. Applicable only when `discount_type=fixed`. - `discount_percent` (float): Discount to apply as a percentage. Applicable only when `discount_type=percent`. - `currency` (string): Three-letter ISO currency code in uppercase. Defaults to your store's base currency. - `customizable` (boolean): Indicates whether the product has custom options enabled. - `date_created` (date, auto): Date and time the product was created. - `date_updated` (date, auto): Date and time the product was last updated. - `delivery` (enum, auto): Method of fulfillment automatically assigned based on `type`: - `shipment` means the product will be physically shipped to a customer. - `subscription` means the product will be fulfilled as a [subscription ](https://developers.swell.is/backend-api/subscriptions/the-subscription-model)when an order is placed. `giftcard` delivery means the product will be fulfilled as a [gift card](https://developers.swell.is/backend-api/pages/the-pages-model) 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` (string): A long-form description of the product. May contain HTML or other markup languages. - `discontinued` (boolean): Indicates whether the product has been discontinued. - `images` (array of object): List of images depicting the bundle. - `id` (objectId, auto): Unique identifier for the image. - `caption` (string): A brief description of the image, intended for display as a caption or alt text. - `file` (object): An object representing the image's source file. - `id` (objectId): Unique identifier for the file. - `filename` (string): Optional file name. - `data` (filedata): A reference to the raw file data. - `content_type` (string): MIME content type of the file. - `date_uploaded` (date): Date the file was uploaded. - `height` (int): Image height in pixels, if applicable. - `length` (int): Size of the file in bytes. - `metadata` (object): A set of arbitrary data that is typically used to store custom values. - `md5` (string): An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes. - `private` (boolean): Indicates whether the file is private. - `url` (string): A public URL to reference the file. Updated automatically if file content changes. - `width` (int): Image width in pixels, if applicable. - `meta_title` (string): Page title used to override product name in storefronts. - `meta_keywords` (string): Page keywords used for search engine optimization purposes. - `meta_description` (string): Page description used for search engine optimization purposes. - `options` (array of object): Options that allow for variations of the base product. If the option is part of a variant or `required=true`, an option value must be set for the product to be added to a cart. - `id` (objectId, auto): Unique identifier for the object. - `name` (string, required): Human-friendly name of the option. - `input_hint` (string): Some brief hint text to help the user understand this option. - `input_type` (enum): Type of user input to display for this option in a storefront. The *select* type is ideal for dropdown or radio selections, *toggle* can be used either to show another option or as a price modifier, and *text* fields can capture user input like a message. - `parent_id` (objectId): Specifies 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_scalar): IDs of parent option values that will make the option appear if selected. - `price` (currency): Extra price for the option, added to the product's `price`/`sale_price`. If the option is part of a variant, the variant's `price`/`sale_price` will override this value. - `required` (boolean): Indicates whether the option requires a value when the product is added to a cart. Default: `{"$formula":"if(input_type == 'toggle', false, true)"}`. - `subscription` (boolean): Indicates whether the option specifies the billing interval of a subscription plan. - `values` (array of object): List of possible values for this option. - `id` (objectId, auto): Unique identifier for the object. - `name` (string, required): Human-friendly name of the option value. - `color` (string): Name of the product color. - `description` (string): A brief description of the option value, intended for displaying to customers. - `price` (currency): Extra price added to the product's `price`/`sale_price` if the option value is selected. Overrides option `price`. - `shipment_weight` (float): Extra weight added to the product's `shipment_weight` if the option value is selected. The unit should match the store's default as configured in general settings. - `subscription_interval` (enum): When product `type=subscription`, this is the billing interval used when this option value is selected. Can be `monthly`, `yearly`, `weekly`, or `daily`. Possible values: `monthly`, `daily`, `weekly`, `yearly`. - `subscription_interval_count` (int): When product `type=subscription`, this number multiplies `subscription_interval` to determine the billing frequency when this option is selected. For example, to make a subscription bill every two weeks, set `subscription_interval=weekly` and `subscription_interval_count=2`. - `subscription_trial_days` (int): When product `type=subscription`, refers to a number of days offered as a trial before an invoice is issued. - `image` (object): Image depicting the product. - `id` (objectId): Unique identifier for the object. - `data` (filedata): A reference to the raw file data. - `date_uploaded` (date): Date the file was uploaded. - `length` (int): Size of the file in bytes. - `md5` (string): An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes. - `filename` (string): Optional file name. - `content_type` (string): MIME content type of the file. - `metadata` (object): Arbitrary data - `private` (boolean) - `url` (string) - `width` (int) - `height` (int) - `attribute_id` (string): Unique identifier for the attribute. - `active` (boolean): Indicates the options are active. Default: `true`. - `input_multi` (boolean): Indicates there are multiple selections for options. - `orig_price` (currency): Reflects the non-sale price of the product - `prices` (array of price): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity of the product that can be sold at once. - `quantity_inc` (int): Specifies a quantify multiple the product must be sold in. - `related_product_ids` (array of child_scalar): Array of related product IDs. - `shipment_dimensions` (object): Product dimensions when packed for shipping. Typically used by third-party carriers in box packing algorithms to optimize shipping costs. - `length` (float, required): Length of the product in `unit`. - `width` (float, required): Width of the product in `unit`. - `height` (float, required): Height of the product in `unit`. - `unit` (enum, required): Either `in`(inches) or `cm`(centimeters). Default: `"in"`. - `shipment_location` (string): ID 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` (float): If specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package. - `shipment_prices` (array of object): Product shipping price rules to override default shipping rules. - `service` (string, required): Shipping service required for this rule to apply. - `account_group` (string): Customer group required for this rule to apply. - `country` (string): Shipping country required for this rule to apply. - `fee_amount` (currency): Fixed amount to add when rule is applied. Only applicable when `fee_type=fixed`. - `fee_percent` (float): Percentage of the shipping price to add when rule is applied. Only applicable when `fee_type=percent`. - `fee_type` (enum): Type of fee to apply in addition to `price`, either `fixed` or `percent`. - `package_quantity` (int): Maximum package quantity when rule is applied. - `price` (currency): Shipping price when rule is applied. - `state` (string): Shipping state required for this rule to apply. - `total_max` (currency): Maximum order subtotal for this rule to apply. - `total_min` (currency): Minimum order subtotal for this rule to apply. - `weight_max` (float): Maximum order item weight for this rule to apply. - `weight_min` (float): Minimum order item weight for this rule to apply. - `zip` (string): Shipping zip/postal code required for this rule to apply. - `shipment_weight` (float): If specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg—depending on the store's default weight unit. - `subscription_interval` (enum): The default billing interval when this product is used as a subscription plan. Can be `monthly`, `yearly`, `weekly`, or `daily`. - `subscription_interval_count` (int): Multiplier when combined with `subscription_interval`. For example, to make a subscription bill every two weeks, set `subscription_interval=weekly` and `subscription_interval_count=2`. - `subscription_trial_days` (int): Number of days offered as a free trial before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued. - `sku` (string): Stock keeping unit (SKU) used to track inventory in a warehouse. - `slug` (string, required): Lowercase, hyphenated identifier typically used in URLs. When creating a product, a `slug` will be generated automatically from the `name`. Maximum length of 1,000 characters. Default: `{"$formula":"slug(name)"}`. - `stock` (array of Stock): Expandable list of stock adjustments for the product. - `stock_backorder` (boolean): Indicates whether the product can be backordered if out of stock. - `stock_level` (int, auto): Quantity of the product currently in stock (including all variants), based on the sum of the stock entries. Includes positive quantities, excluding variants that have negative stock values. - `stock_level_in_locations` (int): Quantity of the product in stock across inventory locations, if the product has no variants. - `stock_level_min` (int, auto): Minimum stock value including all variants. May represent negative variant stock levels. - `stock_level_total` (int, auto): Sum total of all product stock values. - `stock_locations` (object): Stock distributed over inventory locations, if multi-location inventory is enabled. - `available_locations` (array of location): List of custom inventory locations for this product. - `id` (string): Location identifier. - `name` (string): Location name. - `stock_preorder` (boolean): Indicates whether the product can be purchased as a preorder. - `stock_purchasable` (boolean): Indicates whether the product's stock is purchasable. - `stock_status` (enum, auto): String indicating the product's stock status for the purpose of ordering. When `stock_purchasable=true`, an order can be placed for this product regardless of current stock status. Otherwise an order submission will be blocked unless stock status is `available`, `preorder`, or `backorder`. - `stock_tracking` (boolean): Indicates whether the product has stock tracking enabled. - `summary` (string): A brief product summary. - `tags` (array of child_scalar): Array of searchable tags to aid in search discoverability. - `tax_class` (string): Indicates the tax class for the product. - `tax_code` (string): Product tax code for tracking with Avalara, TaxJar, etc. - `theme_template` (string): ID of an alternate theme template used to render this product in a storefront, if applicable. - `type` (string): Implies the ordering and fulfillment options available for the product. Can be `standard`, `subscription`, `bundle`, or `giftcard`. A `standard` product is a physical item that will be shipped to a customer. Default: `"standard"`. - `up_sells` (array of object): List of products to display as up-sells on a product detail page. - `id` (objectId, auto): Unique identifier for the up-sell. - `product_id` (objectId, required): ID of the up-sell product. - `product` (Product): Expandable link to the up-sell product. - `variable` (boolean): Indicates whether the product has variant generation enabled. - `variants` (array of Variants): Expandable list of variants representing unique variations of the product. Each variant is a combination of one or more `options`. For example, Size and Color. - `virtual` (boolean): Indicates whether the product is virtual. ### Quantity and customer-based pricing 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. **See relevant fields** **Fields** - `prices` (array of price): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `id` (objectId): Unique identifier for the product. - `name` (string, required): Human-friendly name of the product. - `active` (boolean): Indicates whether the product is active and available in the storefront. Default: `false`. - `purchase_options` (object): Configuration of one or more purchase options for the product. Can be `standard` for one-time purchases or `subscription` for a subscription plan. Products can support both purchase options simultaneously. - `standard` (object): Designates purchase option as a one-time purchase. - `id` (objectId): ID of the purchase option. - `name` (string, required): The name of the purchase option. - `description` (string): A long-form description of the product. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `price` (currency): List price used when `sale=false` or `sale_price` is not defined. - `sale` (boolean): Indicates whether the product option is on sale. If `true`, the `sale_price` will be used by default when the product is added to a cart. - `sale_price` (currency): Sale price used by default when `sale=true`, overriding `price`. Overrides product sale price. - `prices` (array of object): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `account_groups` (array of string): Array of account groups that are eligible to access the purchase option within the storefront. - `subscription` (object): Designates purchase option for a subscription plan. - `id` (objectId, auto): ID of the subscription plan purchase option. - `name` (string, required): Name of the subscription plan purchase option. - `description` (string): A long-form description of the purchase option. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `account_groups` (array of string): Array of `account_group` names for which the purchase option is available. - `plans` (array of plans): Array defining subscription plans and their respective configurations. - `id` (objectId): ID of the purchase option subscription plan. - `name` (string, required): Name of the subscription plan. - `description` (string): A long-form description of the subscription plan. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the subscription plan is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `price` (currency): List price used when `sale=false` or `sale_price` is not defined. - `prices` (array of object): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `billing_schedule` (object, required): Determines the billing schedule for the subscription plan. - `interval` (enum): Subscription plan billing interval. Can be `daily`, `weekly`, `monthly`, or `yearly`. Possible values: `daily`, `weekly`, `monthly`, `yearly`. Default: `monthly`. - `interval_count` (int, required): Multiplier for billing interval. For example, to make the billing cycle once every two weeks, set `interval=weekly` and `interval_count=2`. Default: `1`. - `limit` (int): Specifies a limit to the number of billing cycles for the subscription plan. For example, `limit=10` would stop billing the customer after the tenth billing cycle. Default: `∞`. - `trial_days` (int): Number 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` (object): An object containing custom attribute values, keyed by each attribute's `id`. A value can be a single value or an array. - `bundle` (boolean): Indicates whether the product is a bundle of other products. - `bundle_items` (array of object): List of products sold as a bundle. Applicable only when `bundle=true`. - `id` (objectId, auto): Unique identifier for the bundle item. - `product_id` (objectId, required): ID of the bundled product. - `product` (Product): Expandable link to the bundled product. - `quantity` (int): Quantity of the bundled product. Defaults to 1. Default: `1`. - `variant_id` (objectId): ID of the bundled variant, if applicable. - `variant` (Product variant): Expandable link to the bundled product variant, if applicable. - `product_name` (string): This field is a copy of the item's `product.name`. Default: `{"$formula": "if(product_id, product.name, null)"}`. - `category` (Category): Expandable link to the primary category. - `category_id` (objectId): Primary category, commonly used as a navigation anchor. - `categories` (Category): Expandable link to all related product categories. - `category_index` (object): Index of categories used for fast lookup operations. - `id` (array of child_scalar): List of related product category IDs. - `sort` (object): Index of category IDs and their respective sort positions. - `code` (string): Unique code to identify the gift card product. - `cost` (currency): Cost of goods (COGS) used to calculate gross margins. - `cross_sells` (array of object): List of products to display as cross-sells on a shopping cart page. - `id` (objectId, auto): Unique identifier for the cross-sell object. - `product_id` (objectId, required): ID of the cross-sell product. - `product` (Product): Expandable link to the cross-sell product. - `discount_type` (enum): Type of discount to apply, either `fixed` or `percent`. - `discount_amount` (currency): Discount to apply as a fixed amount. Applicable only when `discount_type=fixed`. - `discount_percent` (float): Discount to apply as a percentage. Applicable only when `discount_type=percent`. - `currency` (string): Three-letter ISO currency code in uppercase. Defaults to your store's base currency. - `customizable` (boolean): Indicates whether the product has custom options enabled. - `date_created` (date, auto): Date and time the product was created. - `date_updated` (date, auto): Date and time the product was last updated. - `delivery` (enum, auto): Method of fulfillment automatically assigned based on `type`: - `shipment` means the product will be physically shipped to a customer. - `subscription` means the product will be fulfilled as a [subscription ](https://developers.swell.is/backend-api/subscriptions/the-subscription-model)when an order is placed. `giftcard` delivery means the product will be fulfilled as a [gift card](https://developers.swell.is/backend-api/pages/the-pages-model) 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` (string): A long-form description of the product. May contain HTML or other markup languages. - `discontinued` (boolean): Indicates whether the product has been discontinued. - `images` (array of object): List of images depicting the bundle. - `id` (objectId, auto): Unique identifier for the image. - `caption` (string): A brief description of the image, intended for display as a caption or alt text. - `file` (object): An object representing the image's source file. - `id` (objectId): Unique identifier for the file. - `filename` (string): Optional file name. - `data` (filedata): A reference to the raw file data. - `content_type` (string): MIME content type of the file. - `date_uploaded` (date): Date the file was uploaded. - `height` (int): Image height in pixels, if applicable. - `length` (int): Size of the file in bytes. - `metadata` (object): A set of arbitrary data that is typically used to store custom values. - `md5` (string): An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes. - `private` (boolean): Indicates whether the file is private. - `url` (string): A public URL to reference the file. Updated automatically if file content changes. - `width` (int): Image width in pixels, if applicable. - `meta_title` (string): Page title used to override product name in storefronts. - `meta_keywords` (string): Page keywords used for search engine optimization purposes. - `meta_description` (string): Page description used for search engine optimization purposes. - `options` (array of object): Options that allow for variations of the base product. If the option is part of a variant or `required=true`, an option value must be set for the product to be added to a cart. - `id` (objectId, auto): Unique identifier for the object. - `name` (string, required): Human-friendly name of the option. - `input_hint` (string): Some brief hint text to help the user understand this option. - `input_type` (enum): Type of user input to display for this option in a storefront. The *select* type is ideal for dropdown or radio selections, *toggle* can be used either to show another option or as a price modifier, and *text* fields can capture user input like a message. - `parent_id` (objectId): Specifies 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_scalar): IDs of parent option values that will make the option appear if selected. - `price` (currency): Extra price for the option, added to the product's `price`/`sale_price`. If the option is part of a variant, the variant's `price`/`sale_price` will override this value. - `required` (boolean): Indicates whether the option requires a value when the product is added to a cart. Default: `{"$formula":"if(input_type == 'toggle', false, true)"}`. - `subscription` (boolean): Indicates whether the option specifies the billing interval of a subscription plan. - `values` (array of object): List of possible values for this option. - `id` (objectId, auto): Unique identifier for the object. - `name` (string, required): Human-friendly name of the option value. - `color` (string): Name of the product color. - `description` (string): A brief description of the option value, intended for displaying to customers. - `price` (currency): Extra price added to the product's `price`/`sale_price` if the option value is selected. Overrides option `price`. - `shipment_weight` (float): Extra weight added to the product's `shipment_weight` if the option value is selected. The unit should match the store's default as configured in general settings. - `subscription_interval` (enum): When product `type=subscription`, this is the billing interval used when this option value is selected. Can be `monthly`, `yearly`, `weekly`, or `daily`. Possible values: `monthly`, `daily`, `weekly`, `yearly`. - `subscription_interval_count` (int): When product `type=subscription`, this number multiplies `subscription_interval` to determine the billing frequency when this option is selected. For example, to make a subscription bill every two weeks, set `subscription_interval=weekly` and `subscription_interval_count=2`. - `subscription_trial_days` (int): When product `type=subscription`, refers to a number of days offered as a trial before an invoice is issued. - `image` (object): Image depicting the product. - `id` (objectId): Unique identifier for the object. - `data` (filedata): A reference to the raw file data. - `date_uploaded` (date): Date the file was uploaded. - `length` (int): Size of the file in bytes. - `md5` (string): An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes. - `filename` (string): Optional file name. - `content_type` (string): MIME content type of the file. - `metadata` (object): Arbitrary data - `private` (boolean) - `url` (string) - `width` (int) - `height` (int) - `attribute_id` (string): Unique identifier for the attribute. - `active` (boolean): Indicates the options are active. Default: `true`. - `input_multi` (boolean): Indicates there are multiple selections for options. - `orig_price` (currency): Reflects the non-sale price of the product - `price` (currency): List 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. Default: `0`. - `quantity_min` (int): Minimum quantity of the product that can be sold at once. - `quantity_inc` (int): Specifies a quantify multiple the product must be sold in. - `related_product_ids` (array of child_scalar): Array of related product IDs. - `sale` (boolean): Indicates whether the product is on sale. If `true`, the `sale_price` will be used by default when the product is added to a cart. - `sale_price` (currency): Sale price used to override list price when `sale=true`. - `shipment_dimensions` (object): Product dimensions when packed for shipping. Typically used by third-party carriers in box packing algorithms to optimize shipping costs. - `length` (float, required): Length of the product in `unit`. - `width` (float, required): Width of the product in `unit`. - `height` (float, required): Height of the product in `unit`. - `unit` (enum, required): Either `in`(inches) or `cm`(centimeters). Default: `"in"`. - `shipment_location` (string): ID 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` (float): If specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package. - `shipment_prices` (array of object): Product shipping price rules to override default shipping rules. - `service` (string, required): Shipping service required for this rule to apply. - `account_group` (string): Customer group required for this rule to apply. - `country` (string): Shipping country required for this rule to apply. - `fee_amount` (currency): Fixed amount to add when rule is applied. Only applicable when `fee_type=fixed`. - `fee_percent` (float): Percentage of the shipping price to add when rule is applied. Only applicable when `fee_type=percent`. - `fee_type` (enum): Type of fee to apply in addition to `price`, either `fixed` or `percent`. - `package_quantity` (int): Maximum package quantity when rule is applied. - `price` (currency): Shipping price when rule is applied. - `state` (string): Shipping state required for this rule to apply. - `total_max` (currency): Maximum order subtotal for this rule to apply. - `total_min` (currency): Minimum order subtotal for this rule to apply. - `weight_max` (float): Maximum order item weight for this rule to apply. - `weight_min` (float): Minimum order item weight for this rule to apply. - `zip` (string): Shipping zip/postal code required for this rule to apply. - `shipment_weight` (float): If specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg—depending on the store's default weight unit. - `subscription_interval` (enum): The default billing interval when this product is used as a subscription plan. Can be `monthly`, `yearly`, `weekly`, or `daily`. - `subscription_interval_count` (int): Multiplier when combined with `subscription_interval`. For example, to make a subscription bill every two weeks, set `subscription_interval=weekly` and `subscription_interval_count=2`. - `subscription_trial_days` (int): Number of days offered as a free trial before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued. - `sku` (string): Stock keeping unit (SKU) used to track inventory in a warehouse. - `slug` (string, required): Lowercase, hyphenated identifier typically used in URLs. When creating a product, a `slug` will be generated automatically from the `name`. Maximum length of 1,000 characters. Default: `{"$formula":"slug(name)"}`. - `stock` (array of Stock): Expandable list of stock adjustments for the product. - `stock_backorder` (boolean): Indicates whether the product can be backordered if out of stock. - `stock_level` (int, auto): Quantity of the product currently in stock (including all variants), based on the sum of the stock entries. Includes positive quantities, excluding variants that have negative stock values. - `stock_level_in_locations` (int): Quantity of the product in stock across inventory locations, if the product has no variants. - `stock_level_min` (int, auto): Minimum stock value including all variants. May represent negative variant stock levels. - `stock_level_total` (int, auto): Sum total of all product stock values. - `stock_locations` (object): Stock distributed over inventory locations, if multi-location inventory is enabled. - `available_locations` (array of location): List of custom inventory locations for this product. - `id` (string): Location identifier. - `name` (string): Location name. - `stock_preorder` (boolean): Indicates whether the product can be purchased as a preorder. - `stock_purchasable` (boolean): Indicates whether the product's stock is purchasable. - `stock_status` (enum, auto): String indicating the product's stock status for the purpose of ordering. When `stock_purchasable=true`, an order can be placed for this product regardless of current stock status. Otherwise an order submission will be blocked unless stock status is `available`, `preorder`, or `backorder`. - `stock_tracking` (boolean): Indicates whether the product has stock tracking enabled. - `summary` (string): A brief product summary. - `tags` (array of child_scalar): Array of searchable tags to aid in search discoverability. - `tax_class` (string): Indicates the tax class for the product. - `tax_code` (string): Product tax code for tracking with Avalara, TaxJar, etc. - `theme_template` (string): ID of an alternate theme template used to render this product in a storefront, if applicable. - `type` (string): Implies the ordering and fulfillment options available for the product. Can be `standard`, `subscription`, `bundle`, or `giftcard`. A `standard` product is a physical item that will be shipped to a customer. Default: `"standard"`. - `up_sells` (array of object): List of products to display as up-sells on a product detail page. - `id` (objectId, auto): Unique identifier for the up-sell. - `product_id` (objectId, required): ID of the up-sell product. - `product` (Product): Expandable link to the up-sell product. - `variable` (boolean): Indicates whether the product has variant generation enabled. - `variants` (array of Variants): Expandable list of variants representing unique variations of the product. Each variant is a combination of one or more `options`. For example, Size and Color. - `virtual` (boolean): Indicates whether the product is virtual. ### Related products Designate which products a customer would see when on a particular product page by designating additional products as `up_sells` or `cross_sells`. **See relevant fields** **Fields** - `cross_sells` (array of object): List of products to display as cross-sells on a shopping cart page. - `id` (objectId, auto): Unique identifier for the cross-sell object. - `product_id` (objectId, required): ID of the cross-sell product. - `product` (Product): Expandable link to the cross-sell product. - `discount_type` (enum): Type of discount to apply, either `fixed` or `percent`. - `discount_amount` (currency): Discount to apply as a fixed amount. Applicable only when `discount_type=fixed`. - `discount_percent` (float): Discount to apply as a percentage. Applicable only when `discount_type=percent`. - `up_sells` (array of object): List of products to display as up-sells on a product detail page. - `id` (objectId, auto): Unique identifier for the up-sell. - `product_id` (objectId, required): ID of the up-sell product. - `product` (Product): Expandable link to the up-sell product. - `id` (objectId): Unique identifier for the product. - `name` (string, required): Human-friendly name of the product. - `active` (boolean): Indicates whether the product is active and available in the storefront. Default: `false`. - `purchase_options` (object): Configuration of one or more purchase options for the product. Can be `standard` for one-time purchases or `subscription` for a subscription plan. Products can support both purchase options simultaneously. - `standard` (object): Designates purchase option as a one-time purchase. - `id` (objectId): ID of the purchase option. - `name` (string, required): The name of the purchase option. - `description` (string): A long-form description of the product. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `price` (currency): List price used when `sale=false` or `sale_price` is not defined. - `sale` (boolean): Indicates whether the product option is on sale. If `true`, the `sale_price` will be used by default when the product is added to a cart. - `sale_price` (currency): Sale price used by default when `sale=true`, overriding `price`. Overrides product sale price. - `prices` (array of object): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `account_groups` (array of string): Array of account groups that are eligible to access the purchase option within the storefront. - `subscription` (object): Designates purchase option for a subscription plan. - `id` (objectId, auto): ID of the subscription plan purchase option. - `name` (string, required): Name of the subscription plan purchase option. - `description` (string): A long-form description of the purchase option. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `account_groups` (array of string): Array of `account_group` names for which the purchase option is available. - `plans` (array of plans): Array defining subscription plans and their respective configurations. - `id` (objectId): ID of the purchase option subscription plan. - `name` (string, required): Name of the subscription plan. - `description` (string): A long-form description of the subscription plan. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the subscription plan is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `price` (currency): List price used when `sale=false` or `sale_price` is not defined. - `prices` (array of object): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `billing_schedule` (object, required): Determines the billing schedule for the subscription plan. - `interval` (enum): Subscription plan billing interval. Can be `daily`, `weekly`, `monthly`, or `yearly`. Possible values: `daily`, `weekly`, `monthly`, `yearly`. Default: `monthly`. - `interval_count` (int, required): Multiplier for billing interval. For example, to make the billing cycle once every two weeks, set `interval=weekly` and `interval_count=2`. Default: `1`. - `limit` (int): Specifies a limit to the number of billing cycles for the subscription plan. For example, `limit=10` would stop billing the customer after the tenth billing cycle. Default: `∞`. - `trial_days` (int): Number 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` (object): An object containing custom attribute values, keyed by each attribute's `id`. A value can be a single value or an array. - `bundle` (boolean): Indicates whether the product is a bundle of other products. - `bundle_items` (array of object): List of products sold as a bundle. Applicable only when `bundle=true`. - `id` (objectId, auto): Unique identifier for the bundle item. - `product_id` (objectId, required): ID of the bundled product. - `product` (Product): Expandable link to the bundled product. - `quantity` (int): Quantity of the bundled product. Defaults to 1. Default: `1`. - `variant_id` (objectId): ID of the bundled variant, if applicable. - `variant` (Product variant): Expandable link to the bundled product variant, if applicable. - `product_name` (string): This field is a copy of the item's `product.name`. Default: `{"$formula": "if(product_id, product.name, null)"}`. - `category` (Category): Expandable link to the primary category. - `category_id` (objectId): Primary category, commonly used as a navigation anchor. - `categories` (Category): Expandable link to all related product categories. - `category_index` (object): Index of categories used for fast lookup operations. - `id` (array of child_scalar): List of related product category IDs. - `sort` (object): Index of category IDs and their respective sort positions. - `code` (string): Unique code to identify the gift card product. - `cost` (currency): Cost of goods (COGS) used to calculate gross margins. - `currency` (string): Three-letter ISO currency code in uppercase. Defaults to your store's base currency. - `customizable` (boolean): Indicates whether the product has custom options enabled. - `date_created` (date, auto): Date and time the product was created. - `date_updated` (date, auto): Date and time the product was last updated. - `delivery` (enum, auto): Method of fulfillment automatically assigned based on `type`: - `shipment` means the product will be physically shipped to a customer. - `subscription` means the product will be fulfilled as a [subscription ](https://developers.swell.is/backend-api/subscriptions/the-subscription-model)when an order is placed. `giftcard` delivery means the product will be fulfilled as a [gift card](https://developers.swell.is/backend-api/pages/the-pages-model) 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` (string): A long-form description of the product. May contain HTML or other markup languages. - `discontinued` (boolean): Indicates whether the product has been discontinued. - `images` (array of object): List of images depicting the bundle. - `id` (objectId, auto): Unique identifier for the image. - `caption` (string): A brief description of the image, intended for display as a caption or alt text. - `file` (object): An object representing the image's source file. - `id` (objectId): Unique identifier for the file. - `filename` (string): Optional file name. - `data` (filedata): A reference to the raw file data. - `content_type` (string): MIME content type of the file. - `date_uploaded` (date): Date the file was uploaded. - `height` (int): Image height in pixels, if applicable. - `length` (int): Size of the file in bytes. - `metadata` (object): A set of arbitrary data that is typically used to store custom values. - `md5` (string): An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes. - `private` (boolean): Indicates whether the file is private. - `url` (string): A public URL to reference the file. Updated automatically if file content changes. - `width` (int): Image width in pixels, if applicable. - `meta_title` (string): Page title used to override product name in storefronts. - `meta_keywords` (string): Page keywords used for search engine optimization purposes. - `meta_description` (string): Page description used for search engine optimization purposes. - `options` (array of object): Options that allow for variations of the base product. If the option is part of a variant or `required=true`, an option value must be set for the product to be added to a cart. - `id` (objectId, auto): Unique identifier for the object. - `name` (string, required): Human-friendly name of the option. - `input_hint` (string): Some brief hint text to help the user understand this option. - `input_type` (enum): Type of user input to display for this option in a storefront. The *select* type is ideal for dropdown or radio selections, *toggle* can be used either to show another option or as a price modifier, and *text* fields can capture user input like a message. - `parent_id` (objectId): Specifies 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_scalar): IDs of parent option values that will make the option appear if selected. - `price` (currency): Extra price for the option, added to the product's `price`/`sale_price`. If the option is part of a variant, the variant's `price`/`sale_price` will override this value. - `required` (boolean): Indicates whether the option requires a value when the product is added to a cart. Default: `{"$formula":"if(input_type == 'toggle', false, true)"}`. - `subscription` (boolean): Indicates whether the option specifies the billing interval of a subscription plan. - `values` (array of object): List of possible values for this option. - `id` (objectId, auto): Unique identifier for the object. - `name` (string, required): Human-friendly name of the option value. - `color` (string): Name of the product color. - `description` (string): A brief description of the option value, intended for displaying to customers. - `price` (currency): Extra price added to the product's `price`/`sale_price` if the option value is selected. Overrides option `price`. - `shipment_weight` (float): Extra weight added to the product's `shipment_weight` if the option value is selected. The unit should match the store's default as configured in general settings. - `subscription_interval` (enum): When product `type=subscription`, this is the billing interval used when this option value is selected. Can be `monthly`, `yearly`, `weekly`, or `daily`. Possible values: `monthly`, `daily`, `weekly`, `yearly`. - `subscription_interval_count` (int): When product `type=subscription`, this number multiplies `subscription_interval` to determine the billing frequency when this option is selected. For example, to make a subscription bill every two weeks, set `subscription_interval=weekly` and `subscription_interval_count=2`. - `subscription_trial_days` (int): When product `type=subscription`, refers to a number of days offered as a trial before an invoice is issued. - `image` (object): Image depicting the product. - `id` (objectId): Unique identifier for the object. - `data` (filedata): A reference to the raw file data. - `date_uploaded` (date): Date the file was uploaded. - `length` (int): Size of the file in bytes. - `md5` (string): An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes. - `filename` (string): Optional file name. - `content_type` (string): MIME content type of the file. - `metadata` (object): Arbitrary data - `private` (boolean) - `url` (string) - `width` (int) - `height` (int) - `attribute_id` (string): Unique identifier for the attribute. - `active` (boolean): Indicates the options are active. Default: `true`. - `input_multi` (boolean): Indicates there are multiple selections for options. - `orig_price` (currency): Reflects the non-sale price of the product - `price` (currency): List 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. Default: `0`. - `prices` (array of price): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity of the product that can be sold at once. - `quantity_inc` (int): Specifies a quantify multiple the product must be sold in. - `related_product_ids` (array of child_scalar): Array of related product IDs. - `sale` (boolean): Indicates whether the product is on sale. If `true`, the `sale_price` will be used by default when the product is added to a cart. - `sale_price` (currency): Sale price used to override list price when `sale=true`. - `shipment_dimensions` (object): Product dimensions when packed for shipping. Typically used by third-party carriers in box packing algorithms to optimize shipping costs. - `length` (float, required): Length of the product in `unit`. - `width` (float, required): Width of the product in `unit`. - `height` (float, required): Height of the product in `unit`. - `unit` (enum, required): Either `in`(inches) or `cm`(centimeters). Default: `"in"`. - `shipment_location` (string): ID 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` (float): If specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package. - `shipment_prices` (array of object): Product shipping price rules to override default shipping rules. - `service` (string, required): Shipping service required for this rule to apply. - `account_group` (string): Customer group required for this rule to apply. - `country` (string): Shipping country required for this rule to apply. - `fee_amount` (currency): Fixed amount to add when rule is applied. Only applicable when `fee_type=fixed`. - `fee_percent` (float): Percentage of the shipping price to add when rule is applied. Only applicable when `fee_type=percent`. - `fee_type` (enum): Type of fee to apply in addition to `price`, either `fixed` or `percent`. - `package_quantity` (int): Maximum package quantity when rule is applied. - `price` (currency): Shipping price when rule is applied. - `state` (string): Shipping state required for this rule to apply. - `total_max` (currency): Maximum order subtotal for this rule to apply. - `total_min` (currency): Minimum order subtotal for this rule to apply. - `weight_max` (float): Maximum order item weight for this rule to apply. - `weight_min` (float): Minimum order item weight for this rule to apply. - `zip` (string): Shipping zip/postal code required for this rule to apply. - `shipment_weight` (float): If specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg—depending on the store's default weight unit. - `subscription_interval` (enum): The default billing interval when this product is used as a subscription plan. Can be `monthly`, `yearly`, `weekly`, or `daily`. - `subscription_interval_count` (int): Multiplier when combined with `subscription_interval`. For example, to make a subscription bill every two weeks, set `subscription_interval=weekly` and `subscription_interval_count=2`. - `subscription_trial_days` (int): Number of days offered as a free trial before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued. - `sku` (string): Stock keeping unit (SKU) used to track inventory in a warehouse. - `slug` (string, required): Lowercase, hyphenated identifier typically used in URLs. When creating a product, a `slug` will be generated automatically from the `name`. Maximum length of 1,000 characters. Default: `{"$formula":"slug(name)"}`. - `stock` (array of Stock): Expandable list of stock adjustments for the product. - `stock_backorder` (boolean): Indicates whether the product can be backordered if out of stock. - `stock_level` (int, auto): Quantity of the product currently in stock (including all variants), based on the sum of the stock entries. Includes positive quantities, excluding variants that have negative stock values. - `stock_level_in_locations` (int): Quantity of the product in stock across inventory locations, if the product has no variants. - `stock_level_min` (int, auto): Minimum stock value including all variants. May represent negative variant stock levels. - `stock_level_total` (int, auto): Sum total of all product stock values. - `stock_locations` (object): Stock distributed over inventory locations, if multi-location inventory is enabled. - `available_locations` (array of location): List of custom inventory locations for this product. - `id` (string): Location identifier. - `name` (string): Location name. - `stock_preorder` (boolean): Indicates whether the product can be purchased as a preorder. - `stock_purchasable` (boolean): Indicates whether the product's stock is purchasable. - `stock_status` (enum, auto): String indicating the product's stock status for the purpose of ordering. When `stock_purchasable=true`, an order can be placed for this product regardless of current stock status. Otherwise an order submission will be blocked unless stock status is `available`, `preorder`, or `backorder`. - `stock_tracking` (boolean): Indicates whether the product has stock tracking enabled. - `summary` (string): A brief product summary. - `tags` (array of child_scalar): Array of searchable tags to aid in search discoverability. - `tax_class` (string): Indicates the tax class for the product. - `tax_code` (string): Product tax code for tracking with Avalara, TaxJar, etc. - `theme_template` (string): ID of an alternate theme template used to render this product in a storefront, if applicable. - `type` (string): Implies the ordering and fulfillment options available for the product. Can be `standard`, `subscription`, `bundle`, or `giftcard`. A `standard` product is a physical item that will be shipped to a customer. Default: `"standard"`. - `variable` (boolean): Indicates whether the product has variant generation enabled. - `variants` (array of Variants): Expandable list of variants representing unique variations of the product. Each variant is a combination of one or more `options`. For example, Size and Color. - `virtual` (boolean): Indicates whether the product is virtual. ### Content 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. ### Inventory 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. **See related fields ** **Fields** - `stock_level` (int, auto): Quantity of the product currently in stock (including all variants), based on the sum of the stock entries. Includes positive quantities, excluding variants that have negative stock values. - `stock_status` (enum, auto): String indicating the product's stock status for the purpose of ordering. When `stock_purchasable=true`, an order can be placed for this product regardless of current stock status. Otherwise an order submission will be blocked unless stock status is `available`, `preorder`, or `backorder`. - `stock_tracking` (boolean): Indicates whether the product has stock tracking enabled. - `id` (objectId): Unique identifier for the product. - `name` (string, required): Human-friendly name of the product. - `active` (boolean): Indicates whether the product is active and available in the storefront. Default: `false`. - `purchase_options` (object): Configuration of one or more purchase options for the product. Can be `standard` for one-time purchases or `subscription` for a subscription plan. Products can support both purchase options simultaneously. - `standard` (object): Designates purchase option as a one-time purchase. - `id` (objectId): ID of the purchase option. - `name` (string, required): The name of the purchase option. - `description` (string): A long-form description of the product. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `price` (currency): List price used when `sale=false` or `sale_price` is not defined. - `sale` (boolean): Indicates whether the product option is on sale. If `true`, the `sale_price` will be used by default when the product is added to a cart. - `sale_price` (currency): Sale price used by default when `sale=true`, overriding `price`. Overrides product sale price. - `prices` (array of object): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `account_groups` (array of string): Array of account groups that are eligible to access the purchase option within the storefront. - `subscription` (object): Designates purchase option for a subscription plan. - `id` (objectId, auto): ID of the subscription plan purchase option. - `name` (string, required): Name of the subscription plan purchase option. - `description` (string): A long-form description of the purchase option. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `account_groups` (array of string): Array of `account_group` names for which the purchase option is available. - `plans` (array of plans): Array defining subscription plans and their respective configurations. - `id` (objectId): ID of the purchase option subscription plan. - `name` (string, required): Name of the subscription plan. - `description` (string): A long-form description of the subscription plan. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the subscription plan is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `price` (currency): List price used when `sale=false` or `sale_price` is not defined. - `prices` (array of object): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `billing_schedule` (object, required): Determines the billing schedule for the subscription plan. - `interval` (enum): Subscription plan billing interval. Can be `daily`, `weekly`, `monthly`, or `yearly`. Possible values: `daily`, `weekly`, `monthly`, `yearly`. Default: `monthly`. - `interval_count` (int, required): Multiplier for billing interval. For example, to make the billing cycle once every two weeks, set `interval=weekly` and `interval_count=2`. Default: `1`. - `limit` (int): Specifies a limit to the number of billing cycles for the subscription plan. For example, `limit=10` would stop billing the customer after the tenth billing cycle. Default: `∞`. - `trial_days` (int): Number 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` (object): An object containing custom attribute values, keyed by each attribute's `id`. A value can be a single value or an array. - `bundle` (boolean): Indicates whether the product is a bundle of other products. - `bundle_items` (array of object): List of products sold as a bundle. Applicable only when `bundle=true`. - `id` (objectId, auto): Unique identifier for the bundle item. - `product_id` (objectId, required): ID of the bundled product. - `product` (Product): Expandable link to the bundled product. - `quantity` (int): Quantity of the bundled product. Defaults to 1. Default: `1`. - `variant_id` (objectId): ID of the bundled variant, if applicable. - `variant` (Product variant): Expandable link to the bundled product variant, if applicable. - `product_name` (string): This field is a copy of the item's `product.name`. Default: `{"$formula": "if(product_id, product.name, null)"}`. - `category` (Category): Expandable link to the primary category. - `category_id` (objectId): Primary category, commonly used as a navigation anchor. - `categories` (Category): Expandable link to all related product categories. - `category_index` (object): Index of categories used for fast lookup operations. - `id` (array of child_scalar): List of related product category IDs. - `sort` (object): Index of category IDs and their respective sort positions. - `code` (string): Unique code to identify the gift card product. - `cost` (currency): Cost of goods (COGS) used to calculate gross margins. - `cross_sells` (array of object): List of products to display as cross-sells on a shopping cart page. - `id` (objectId, auto): Unique identifier for the cross-sell object. - `product_id` (objectId, required): ID of the cross-sell product. - `product` (Product): Expandable link to the cross-sell product. - `discount_type` (enum): Type of discount to apply, either `fixed` or `percent`. - `discount_amount` (currency): Discount to apply as a fixed amount. Applicable only when `discount_type=fixed`. - `discount_percent` (float): Discount to apply as a percentage. Applicable only when `discount_type=percent`. - `currency` (string): Three-letter ISO currency code in uppercase. Defaults to your store's base currency. - `customizable` (boolean): Indicates whether the product has custom options enabled. - `date_created` (date, auto): Date and time the product was created. - `date_updated` (date, auto): Date and time the product was last updated. - `delivery` (enum, auto): Method of fulfillment automatically assigned based on `type`: - `shipment` means the product will be physically shipped to a customer. - `subscription` means the product will be fulfilled as a [subscription ](https://developers.swell.is/backend-api/subscriptions/the-subscription-model)when an order is placed. `giftcard` delivery means the product will be fulfilled as a [gift card](https://developers.swell.is/backend-api/pages/the-pages-model) 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` (string): A long-form description of the product. May contain HTML or other markup languages. - `discontinued` (boolean): Indicates whether the product has been discontinued. - `images` (array of object): List of images depicting the bundle. - `id` (objectId, auto): Unique identifier for the image. - `caption` (string): A brief description of the image, intended for display as a caption or alt text. - `file` (object): An object representing the image's source file. - `id` (objectId): Unique identifier for the file. - `filename` (string): Optional file name. - `data` (filedata): A reference to the raw file data. - `content_type` (string): MIME content type of the file. - `date_uploaded` (date): Date the file was uploaded. - `height` (int): Image height in pixels, if applicable. - `length` (int): Size of the file in bytes. - `metadata` (object): A set of arbitrary data that is typically used to store custom values. - `md5` (string): An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes. - `private` (boolean): Indicates whether the file is private. - `url` (string): A public URL to reference the file. Updated automatically if file content changes. - `width` (int): Image width in pixels, if applicable. - `meta_title` (string): Page title used to override product name in storefronts. - `meta_keywords` (string): Page keywords used for search engine optimization purposes. - `meta_description` (string): Page description used for search engine optimization purposes. - `options` (array of object): Options that allow for variations of the base product. If the option is part of a variant or `required=true`, an option value must be set for the product to be added to a cart. - `id` (objectId, auto): Unique identifier for the object. - `name` (string, required): Human-friendly name of the option. - `input_hint` (string): Some brief hint text to help the user understand this option. - `input_type` (enum): Type of user input to display for this option in a storefront. The *select* type is ideal for dropdown or radio selections, *toggle* can be used either to show another option or as a price modifier, and *text* fields can capture user input like a message. - `parent_id` (objectId): Specifies 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_scalar): IDs of parent option values that will make the option appear if selected. - `price` (currency): Extra price for the option, added to the product's `price`/`sale_price`. If the option is part of a variant, the variant's `price`/`sale_price` will override this value. - `required` (boolean): Indicates whether the option requires a value when the product is added to a cart. Default: `{"$formula":"if(input_type == 'toggle', false, true)"}`. - `subscription` (boolean): Indicates whether the option specifies the billing interval of a subscription plan. - `values` (array of object): List of possible values for this option. - `id` (objectId, auto): Unique identifier for the object. - `name` (string, required): Human-friendly name of the option value. - `color` (string): Name of the product color. - `description` (string): A brief description of the option value, intended for displaying to customers. - `price` (currency): Extra price added to the product's `price`/`sale_price` if the option value is selected. Overrides option `price`. - `shipment_weight` (float): Extra weight added to the product's `shipment_weight` if the option value is selected. The unit should match the store's default as configured in general settings. - `subscription_interval` (enum): When product `type=subscription`, this is the billing interval used when this option value is selected. Can be `monthly`, `yearly`, `weekly`, or `daily`. Possible values: `monthly`, `daily`, `weekly`, `yearly`. - `subscription_interval_count` (int): When product `type=subscription`, this number multiplies `subscription_interval` to determine the billing frequency when this option is selected. For example, to make a subscription bill every two weeks, set `subscription_interval=weekly` and `subscription_interval_count=2`. - `subscription_trial_days` (int): When product `type=subscription`, refers to a number of days offered as a trial before an invoice is issued. - `image` (object): Image depicting the product. - `id` (objectId): Unique identifier for the object. - `data` (filedata): A reference to the raw file data. - `date_uploaded` (date): Date the file was uploaded. - `length` (int): Size of the file in bytes. - `md5` (string): An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes. - `filename` (string): Optional file name. - `content_type` (string): MIME content type of the file. - `metadata` (object): Arbitrary data - `private` (boolean) - `url` (string) - `width` (int) - `height` (int) - `attribute_id` (string): Unique identifier for the attribute. - `active` (boolean): Indicates the options are active. Default: `true`. - `input_multi` (boolean): Indicates there are multiple selections for options. - `orig_price` (currency): Reflects the non-sale price of the product - `price` (currency): List 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. Default: `0`. - `prices` (array of price): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity of the product that can be sold at once. - `quantity_inc` (int): Specifies a quantify multiple the product must be sold in. - `related_product_ids` (array of child_scalar): Array of related product IDs. - `sale` (boolean): Indicates whether the product is on sale. If `true`, the `sale_price` will be used by default when the product is added to a cart. - `sale_price` (currency): Sale price used to override list price when `sale=true`. - `shipment_dimensions` (object): Product dimensions when packed for shipping. Typically used by third-party carriers in box packing algorithms to optimize shipping costs. - `length` (float, required): Length of the product in `unit`. - `width` (float, required): Width of the product in `unit`. - `height` (float, required): Height of the product in `unit`. - `unit` (enum, required): Either `in`(inches) or `cm`(centimeters). Default: `"in"`. - `shipment_location` (string): ID 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` (float): If specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package. - `shipment_prices` (array of object): Product shipping price rules to override default shipping rules. - `service` (string, required): Shipping service required for this rule to apply. - `account_group` (string): Customer group required for this rule to apply. - `country` (string): Shipping country required for this rule to apply. - `fee_amount` (currency): Fixed amount to add when rule is applied. Only applicable when `fee_type=fixed`. - `fee_percent` (float): Percentage of the shipping price to add when rule is applied. Only applicable when `fee_type=percent`. - `fee_type` (enum): Type of fee to apply in addition to `price`, either `fixed` or `percent`. - `package_quantity` (int): Maximum package quantity when rule is applied. - `price` (currency): Shipping price when rule is applied. - `state` (string): Shipping state required for this rule to apply. - `total_max` (currency): Maximum order subtotal for this rule to apply. - `total_min` (currency): Minimum order subtotal for this rule to apply. - `weight_max` (float): Maximum order item weight for this rule to apply. - `weight_min` (float): Minimum order item weight for this rule to apply. - `zip` (string): Shipping zip/postal code required for this rule to apply. - `shipment_weight` (float): If specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg—depending on the store's default weight unit. - `subscription_interval` (enum): The default billing interval when this product is used as a subscription plan. Can be `monthly`, `yearly`, `weekly`, or `daily`. - `subscription_interval_count` (int): Multiplier when combined with `subscription_interval`. For example, to make a subscription bill every two weeks, set `subscription_interval=weekly` and `subscription_interval_count=2`. - `subscription_trial_days` (int): Number of days offered as a free trial before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued. - `sku` (string): Stock keeping unit (SKU) used to track inventory in a warehouse. - `slug` (string, required): Lowercase, hyphenated identifier typically used in URLs. When creating a product, a `slug` will be generated automatically from the `name`. Maximum length of 1,000 characters. Default: `{"$formula":"slug(name)"}`. - `stock` (array of Stock): Expandable list of stock adjustments for the product. - `stock_backorder` (boolean): Indicates whether the product can be backordered if out of stock. - `stock_level_in_locations` (int): Quantity of the product in stock across inventory locations, if the product has no variants. - `stock_level_min` (int, auto): Minimum stock value including all variants. May represent negative variant stock levels. - `stock_level_total` (int, auto): Sum total of all product stock values. - `stock_locations` (object): Stock distributed over inventory locations, if multi-location inventory is enabled. - `available_locations` (array of location): List of custom inventory locations for this product. - `id` (string): Location identifier. - `name` (string): Location name. - `stock_preorder` (boolean): Indicates whether the product can be purchased as a preorder. - `stock_purchasable` (boolean): Indicates whether the product's stock is purchasable. - `summary` (string): A brief product summary. - `tags` (array of child_scalar): Array of searchable tags to aid in search discoverability. - `tax_class` (string): Indicates the tax class for the product. - `tax_code` (string): Product tax code for tracking with Avalara, TaxJar, etc. - `theme_template` (string): ID of an alternate theme template used to render this product in a storefront, if applicable. - `type` (string): Implies the ordering and fulfillment options available for the product. Can be `standard`, `subscription`, `bundle`, or `giftcard`. A `standard` product is a physical item that will be shipped to a customer. Default: `"standard"`. - `up_sells` (array of object): List of products to display as up-sells on a product detail page. - `id` (objectId, auto): Unique identifier for the up-sell. - `product_id` (objectId, required): ID of the up-sell product. - `product` (Product): Expandable link to the up-sell product. - `variable` (boolean): Indicates whether the product has variant generation enabled. - `variants` (array of Variants): Expandable list of variants representing unique variations of the product. Each variant is a combination of one or more `options`. For example, Size and Color. - `virtual` (boolean): Indicates whether the product is virtual. ### Shipping 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. **See relevant fields ** **Fields** - `shipment_dimensions` (object): Product dimensions when packed for shipping. Typically used by third-party carriers in box packing algorithms to optimize shipping costs. - `length` (float, required): Length of the product in `unit`. - `width` (float, required): Width of the product in `unit`. - `height` (float, required): Height of the product in `unit`. - `unit` (enum, required): Either `in`(inches) or `cm`(centimeters). Default: `"in"`. - `shipment_location` (string): ID 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 object): Product shipping price rules to override default shipping rules. - `service` (string, required): Shipping service required for this rule to apply. - `account_group` (string): Customer group required for this rule to apply. - `country` (string): Shipping country required for this rule to apply. - `fee_amount` (currency): Fixed amount to add when rule is applied. Only applicable when `fee_type=fixed`. - `fee_percent` (float): Percentage of the shipping price to add when rule is applied. Only applicable when `fee_type=percent`. - `fee_type` (enum): Type of fee to apply in addition to `price`, either `fixed` or `percent`. - `package_quantity` (int): Maximum package quantity when rule is applied. - `price` (currency): Shipping price when rule is applied. - `state` (string): Shipping state required for this rule to apply. - `total_max` (currency): Maximum order subtotal for this rule to apply. - `total_min` (currency): Minimum order subtotal for this rule to apply. - `weight_max` (float): Maximum order item weight for this rule to apply. - `weight_min` (float): Minimum order item weight for this rule to apply. - `zip` (string): Shipping zip/postal code required for this rule to apply. - `shipment_weight` (float): If specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg—depending on the store's default weight unit. - `id` (objectId): Unique identifier for the product. - `name` (string, required): Human-friendly name of the product. - `active` (boolean): Indicates whether the product is active and available in the storefront. Default: `false`. - `purchase_options` (object): Configuration of one or more purchase options for the product. Can be `standard` for one-time purchases or `subscription` for a subscription plan. Products can support both purchase options simultaneously. - `standard` (object): Designates purchase option as a one-time purchase. - `id` (objectId): ID of the purchase option. - `name` (string, required): The name of the purchase option. - `description` (string): A long-form description of the product. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `price` (currency): List price used when `sale=false` or `sale_price` is not defined. - `sale` (boolean): Indicates whether the product option is on sale. If `true`, the `sale_price` will be used by default when the product is added to a cart. - `sale_price` (currency): Sale price used by default when `sale=true`, overriding `price`. Overrides product sale price. - `prices` (array of object): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `account_groups` (array of string): Array of account groups that are eligible to access the purchase option within the storefront. - `subscription` (object): Designates purchase option for a subscription plan. - `id` (objectId, auto): ID of the subscription plan purchase option. - `name` (string, required): Name of the subscription plan purchase option. - `description` (string): A long-form description of the purchase option. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `account_groups` (array of string): Array of `account_group` names for which the purchase option is available. - `plans` (array of plans): Array defining subscription plans and their respective configurations. - `id` (objectId): ID of the purchase option subscription plan. - `name` (string, required): Name of the subscription plan. - `description` (string): A long-form description of the subscription plan. May contain HTML or other markup languages. - `active` (boolean): Indicates whether the subscription plan is available for customers to purchase. Inactive products will not be returned on the [Frontend](https://developers.swell.is/frontend-api/introduction). Default: `false`. - `price` (currency): List price used when `sale=false` or `sale_price` is not defined. - `prices` (array of object): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `billing_schedule` (object, required): Determines the billing schedule for the subscription plan. - `interval` (enum): Subscription plan billing interval. Can be `daily`, `weekly`, `monthly`, or `yearly`. Possible values: `daily`, `weekly`, `monthly`, `yearly`. Default: `monthly`. - `interval_count` (int, required): Multiplier for billing interval. For example, to make the billing cycle once every two weeks, set `interval=weekly` and `interval_count=2`. Default: `1`. - `limit` (int): Specifies a limit to the number of billing cycles for the subscription plan. For example, `limit=10` would stop billing the customer after the tenth billing cycle. Default: `∞`. - `trial_days` (int): Number 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` (object): An object containing custom attribute values, keyed by each attribute's `id`. A value can be a single value or an array. - `bundle` (boolean): Indicates whether the product is a bundle of other products. - `bundle_items` (array of object): List of products sold as a bundle. Applicable only when `bundle=true`. - `id` (objectId, auto): Unique identifier for the bundle item. - `product_id` (objectId, required): ID of the bundled product. - `product` (Product): Expandable link to the bundled product. - `quantity` (int): Quantity of the bundled product. Defaults to 1. Default: `1`. - `variant_id` (objectId): ID of the bundled variant, if applicable. - `variant` (Product variant): Expandable link to the bundled product variant, if applicable. - `product_name` (string): This field is a copy of the item's `product.name`. Default: `{"$formula": "if(product_id, product.name, null)"}`. - `category` (Category): Expandable link to the primary category. - `category_id` (objectId): Primary category, commonly used as a navigation anchor. - `categories` (Category): Expandable link to all related product categories. - `category_index` (object): Index of categories used for fast lookup operations. - `id` (array of child_scalar): List of related product category IDs. - `sort` (object): Index of category IDs and their respective sort positions. - `code` (string): Unique code to identify the gift card product. - `cost` (currency): Cost of goods (COGS) used to calculate gross margins. - `cross_sells` (array of object): List of products to display as cross-sells on a shopping cart page. - `id` (objectId, auto): Unique identifier for the cross-sell object. - `product_id` (objectId, required): ID of the cross-sell product. - `product` (Product): Expandable link to the cross-sell product. - `discount_type` (enum): Type of discount to apply, either `fixed` or `percent`. - `discount_amount` (currency): Discount to apply as a fixed amount. Applicable only when `discount_type=fixed`. - `discount_percent` (float): Discount to apply as a percentage. Applicable only when `discount_type=percent`. - `currency` (string): Three-letter ISO currency code in uppercase. Defaults to your store's base currency. - `customizable` (boolean): Indicates whether the product has custom options enabled. - `date_created` (date, auto): Date and time the product was created. - `date_updated` (date, auto): Date and time the product was last updated. - `delivery` (enum, auto): Method of fulfillment automatically assigned based on `type`: - `shipment` means the product will be physically shipped to a customer. - `subscription` means the product will be fulfilled as a [subscription ](https://developers.swell.is/backend-api/subscriptions/the-subscription-model)when an order is placed. `giftcard` delivery means the product will be fulfilled as a [gift card](https://developers.swell.is/backend-api/pages/the-pages-model) 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` (string): A long-form description of the product. May contain HTML or other markup languages. - `discontinued` (boolean): Indicates whether the product has been discontinued. - `images` (array of object): List of images depicting the bundle. - `id` (objectId, auto): Unique identifier for the image. - `caption` (string): A brief description of the image, intended for display as a caption or alt text. - `file` (object): An object representing the image's source file. - `id` (objectId): Unique identifier for the file. - `filename` (string): Optional file name. - `data` (filedata): A reference to the raw file data. - `content_type` (string): MIME content type of the file. - `date_uploaded` (date): Date the file was uploaded. - `height` (int): Image height in pixels, if applicable. - `length` (int): Size of the file in bytes. - `metadata` (object): A set of arbitrary data that is typically used to store custom values. - `md5` (string): An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes. - `private` (boolean): Indicates whether the file is private. - `url` (string): A public URL to reference the file. Updated automatically if file content changes. - `width` (int): Image width in pixels, if applicable. - `meta_title` (string): Page title used to override product name in storefronts. - `meta_keywords` (string): Page keywords used for search engine optimization purposes. - `meta_description` (string): Page description used for search engine optimization purposes. - `options` (array of object): Options that allow for variations of the base product. If the option is part of a variant or `required=true`, an option value must be set for the product to be added to a cart. - `id` (objectId, auto): Unique identifier for the object. - `name` (string, required): Human-friendly name of the option. - `input_hint` (string): Some brief hint text to help the user understand this option. - `input_type` (enum): Type of user input to display for this option in a storefront. The *select* type is ideal for dropdown or radio selections, *toggle* can be used either to show another option or as a price modifier, and *text* fields can capture user input like a message. - `parent_id` (objectId): Specifies 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_scalar): IDs of parent option values that will make the option appear if selected. - `price` (currency): Extra price for the option, added to the product's `price`/`sale_price`. If the option is part of a variant, the variant's `price`/`sale_price` will override this value. - `required` (boolean): Indicates whether the option requires a value when the product is added to a cart. Default: `{"$formula":"if(input_type == 'toggle', false, true)"}`. - `subscription` (boolean): Indicates whether the option specifies the billing interval of a subscription plan. - `values` (array of object): List of possible values for this option. - `id` (objectId, auto): Unique identifier for the object. - `name` (string, required): Human-friendly name of the option value. - `color` (string): Name of the product color. - `description` (string): A brief description of the option value, intended for displaying to customers. - `price` (currency): Extra price added to the product's `price`/`sale_price` if the option value is selected. Overrides option `price`. - `shipment_weight` (float): Extra weight added to the product's `shipment_weight` if the option value is selected. The unit should match the store's default as configured in general settings. - `subscription_interval` (enum): When product `type=subscription`, this is the billing interval used when this option value is selected. Can be `monthly`, `yearly`, `weekly`, or `daily`. Possible values: `monthly`, `daily`, `weekly`, `yearly`. - `subscription_interval_count` (int): When product `type=subscription`, this number multiplies `subscription_interval` to determine the billing frequency when this option is selected. For example, to make a subscription bill every two weeks, set `subscription_interval=weekly` and `subscription_interval_count=2`. - `subscription_trial_days` (int): When product `type=subscription`, refers to a number of days offered as a trial before an invoice is issued. - `image` (object): Image depicting the product. - `id` (objectId): Unique identifier for the object. - `data` (filedata): A reference to the raw file data. - `date_uploaded` (date): Date the file was uploaded. - `length` (int): Size of the file in bytes. - `md5` (string): An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes. - `filename` (string): Optional file name. - `content_type` (string): MIME content type of the file. - `metadata` (object): Arbitrary data - `private` (boolean) - `url` (string) - `width` (int) - `height` (int) - `attribute_id` (string): Unique identifier for the attribute. - `active` (boolean): Indicates the options are active. Default: `true`. - `input_multi` (boolean): Indicates there are multiple selections for options. - `orig_price` (currency): Reflects the non-sale price of the product - `price` (currency): List 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. Default: `0`. - `prices` (array of price): Price rules determined by cart quantity or customer account group. Overrides `price` and `sale_price` when conditions match. - `price` (currency, required): Price applied when conditions are met. - `account_group` (string): Customer account group as a condition to apply price. - `quantity_max` (int): Maximum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity as a condition to apply price. - `quantity_min` (int): Minimum quantity of the product that can be sold at once. - `quantity_inc` (int): Specifies a quantify multiple the product must be sold in. - `related_product_ids` (array of child_scalar): Array of related product IDs. - `sale` (boolean): Indicates whether the product is on sale. If `true`, the `sale_price` will be used by default when the product is added to a cart. - `sale_price` (currency): Sale price used to override list price when `sale=true`. - `shipment_package_quantity` (float): If specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package. - `subscription_interval` (enum): The default billing interval when this product is used as a subscription plan. Can be `monthly`, `yearly`, `weekly`, or `daily`. - `subscription_interval_count` (int): Multiplier when combined with `subscription_interval`. For example, to make a subscription bill every two weeks, set `subscription_interval=weekly` and `subscription_interval_count=2`. - `subscription_trial_days` (int): Number of days offered as a free trial before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued. - `sku` (string): Stock keeping unit (SKU) used to track inventory in a warehouse. - `slug` (string, required): Lowercase, hyphenated identifier typically used in URLs. When creating a product, a `slug` will be generated automatically from the `name`. Maximum length of 1,000 characters. Default: `{"$formula":"slug(name)"}`. - `stock` (array of Stock): Expandable list of stock adjustments for the product. - `stock_backorder` (boolean): Indicates whether the product can be backordered if out of stock. - `stock_level` (int, auto): Quantity of the product currently in stock (including all variants), based on the sum of the stock entries. Includes positive quantities, excluding variants that have negative stock values. - `stock_level_in_locations` (int): Quantity of the product in stock across inventory locations, if the product has no variants. - `stock_level_min` (int, auto): Minimum stock value including all variants. May represent negative variant stock levels. - `stock_level_total` (int, auto): Sum total of all product stock values. - `stock_locations` (object): Stock distributed over inventory locations, if multi-location inventory is enabled. - `available_locations` (array of location): List of custom inventory locations for this product. - `id` (string): Location identifier. - `name` (string): Location name. - `stock_preorder` (boolean): Indicates whether the product can be purchased as a preorder. - `stock_purchasable` (boolean): Indicates whether the product's stock is purchasable. - `stock_status` (enum, auto): String indicating the product's stock status for the purpose of ordering. When `stock_purchasable=true`, an order can be placed for this product regardless of current stock status. Otherwise an order submission will be blocked unless stock status is `available`, `preorder`, or `backorder`. - `stock_tracking` (boolean): Indicates whether the product has stock tracking enabled. - `summary` (string): A brief product summary. - `tags` (array of child_scalar): Array of searchable tags to aid in search discoverability. - `tax_class` (string): Indicates the tax class for the product. - `tax_code` (string): Product tax code for tracking with Avalara, TaxJar, etc. - `theme_template` (string): ID of an alternate theme template used to render this product in a storefront, if applicable. - `type` (string): Implies the ordering and fulfillment options available for the product. Can be `standard`, `subscription`, `bundle`, or `giftcard`. A `standard` product is a physical item that will be shipped to a customer. Default: `"standard"`. - `up_sells` (array of object): List of products to display as up-sells on a product detail page. - `id` (objectId, auto): Unique identifier for the up-sell. - `product_id` (objectId, required): ID of the up-sell product. - `product` (Product): Expandable link to the up-sell product. - `variable` (boolean): Indicates whether the product has variant generation enabled. - `variants` (array of Variants): Expandable list of variants representing unique variations of the product. Each variant is a combination of one or more `options`. For example, Size and Color. - `virtual` (boolean): Indicates whether the product is virtual. ### Up next 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.