# Products

Source: https://developers.swell.is/backend-api/products

Products represent items that can be sold to a customer, either as one-off sales or as subscriptions. For more complex subscription products and when physical items are involved, it's recommended to create a subscription plan.

## The product model

### Fields

- `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` (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`. Possible values: `fixed`, `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.* Possible values: `shipment`, `subscription`, `giftcard`.
- `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. Possible values: `select`, `toggle`, `short_text`, `long_text`, `toggle`.
  - `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). Possible values: `in`, `cm`. 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`. Possible values: `fixed`, `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`. Possible values: `monthly`, `daily`, `weekly`, `yearly`.
- `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`. Possible values: `discontinued`, `preorder`, `backorder`, `out_of_stock`, `in_stock`.
- `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.

### Example response

```json
{
  "name": "Iron dagger",
  "sku": "00090616",
  "active": true,
  "purchase_options": {
    "standard": {
      "active": true,
      "price": 10,
      "sale_price": null,
      "sale": false,
      "prices": []
    },
    "subscription": {
      "active": true,
      "plans": [
        {
          "name": "Monthly",
          "description": "1 dagger/month",
          "price": 9,
          "billing_schedule": {
            "interval": "monthly",
            "interval_count": 1,
            "limit": null,
            "trial_days": 14
          },
          "id": "627c6f180d375a001296b593",
          "active": true
        }
      ]
    }
  },
  "variable": true,
  "description": "<h3>Damage: 7</h3><h3>Weight: 8</h3><h3>Health: 98</h3><h3>Speed: 1.4</h3><h3>Reach: 0.6</h3>",
  "tags": [],
  "meta_title": null,
  "meta_description": null,
  "slug": "iron-dagger",
  "attributes": {
    "blade": "",
    "dagger": "",
    "type": [
      "Fine",
      "Rusty"
    ]
  },
  "delivery": "shipment",
  "bundle": null,
  "price": 10,
  "stock_tracking": false,
  "options": [
    {
      "id": "627c6e36e80393798c171670",
      "values": [
        {
          "id": "627c6f18e80393798c171673",
          "name": "Fine",
          "price": null,
          "shipment_weight": null,
          "description": "A better-than-usual iron dagger"
        },
        {
          "id": "627c6f18e80393798c171674",
          "name": "Rusty",
          "price": 0,
          "shipment_weight": null,
          "description": "This dagger's seen better days"
        }
      ],
      "name": "Type",
      "active": true,
      "input_type": "select",
      "variant": true,
      "description": null,
      "required": true,
      "attribute_id": "type"
    }
  ],
  "currency": "USD",
  "sale": false,
  "sale_price": null,
  "prices": [],
  "type": "standard",
  "tax_class": "standard",
  "date_created": "2022-05-12T02:21:12.534Z",
  "stock_status": null,
  "date_updated": "2022-05-12T02:37:45.666Z",
  "category_index": {
    "sort": {
      "627c6db5632818001272f8ed": 0,
      "627c6dc30d375a001296a8b7": 0
    },
    "id": [
      "627c6db5632818001272f8ed",
      "627c6dc30d375a001296a8b7"
    ]
  },
  "cross_sells": [],
  "up_sells": [
    {
      "id": "627c7225e80393798c17167b",
      "product_id": "627c715e632818001274ebd8"
    }
  ],
  "id": "627c6f180d375a001296b580"
```


## Create a product

Create a new product.

A product's `attributes` object is keyed by each attribute's `id`, so the attribute must exist before a product can reference it. An attribute's `id` defaults to its `name` in underscored form and cannot be changed afterwards.

**Create a product with an attribute**

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

// Create the attribute first. Its id is derived from the name,
// so this attribute is referenced as `material`.
await swell.post('/attributes', {
  name: 'Material',
  type: 'select',
  values: ['Silver', 'Gold', 'Titanium'],
  visible: true,
  filterable: true
});

// Create a product that uses it, keyed by the attribute id
await swell.post('/products', {
  name: 'Signet Ring',
  price: 149.00,
  active: true,
  attributes: {
    material: 'Silver'
  }
});

// A value can also be an array
await swell.post('/products', {
  name: 'Mixed Metal Bangle',
  price: 89.00,
  active: true,
  attributes: {
    material: ['Silver', 'Gold']
  }
});
```

Variant attributes are created a different way. An option with `variant` set to `true` and at least one value creates or updates the matching attribute record automatically, and fills in the product's `attributes` from the option values.

### Arguments

- `name` (string, required): Human-friendly name 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`.
- `attributes` (object): An object containing custom attribute key/value pairs. See [attributes](https://developers.swell.is/backend-api/attributes/the-attribute-model) for more details.
- `slug` (string): 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)"}`.
- `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 as a subscription plan.
    - `id` (objectId): 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 object): 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: `fasle`.
      - `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, required): Subscription plan billing interval. Can be `daily`, `weekly`, `monthly`, or `yearly`. Possible values: `daily`, `weekly`, `monthly`, `yearly`.
        - `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: `∞`.
- `active` (boolean): Set `true` to make the product visible to customers in a storefront, otherwise it will be hidden. Default: `false`.
- `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`.
  - `product_id` (objectId, required): ID of 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.
- `categories` (Category): Expandable link to all related product categories.
- `category` (Category): Expandable link to the primary category.
- `category_id` (objectId): Primary category, commonly used as a navigation anchor.
- `category_index` (object): Index of categories used for fast lookup operations.
  - `sort` (object): Index of category IDs and their respective sort positions.
    - `*` (int)
- `code` (string): Unique code to identify the gift card product.
- `cost` (currency): Cost of goods (COGS) that is used to calculate gross margins.
- `cross_sells` (array of object): List of products to display as cross-sells on a shopping cart page.
  - `product_id` (objectId, required): ID of the cross-sell product.
  - `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`.
  - `discount_type` (enum): Type of discount to apply, either `fixed` or `percent`. Possible values: `fixed`, `percent`.
- `currency` (string): Three-letter ISO currency code in uppercase. Defaults to your store's base currency.
- `customizable` (boolean): Set `true` to enable custom options for this product in the admin panel.
- `delivery` (enum): 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.* Possible values: `shipment`, `subscription`, `giftcard`.
- `description` (string): A long form description of the product. May have HTML or other markup.
- `discontinued` (boolean): Indicates whether the product has been discontinued.
- `images` (array of object): List of images depicting the bundle.
  - `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.
    - `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): A set of arbitrary data that is typically used to store custom values.
    - `data` (filedata): Set or overwrite file data. Use the following format when writing a file from binary data (for example an image): `data[$binary]=<base64 encoded binary data>`.
    - `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.
    - `height` (int): Image height in pixels, if applicable.
- `meta_description` (string): Page description used for search engine optimization purposes.
- `meta_keywords` (string): Page keywords used for search engine optimization purposes.
- `meta_title` (string): Page title used to override product name in storefronts.
- `prices` (array of object): Set price rules to use when conditions match the customer's account group or product quantity in a cart.
  - `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_inc` (int): Specifies a quantified multiple the product must be sold in.
- `quantity_min` (int): Minimum quantity of the product that can be sold at once.
- `related_product_ids` (array of child_scalar): Array of related product IDs.
- `sale` (boolean): Set `true` to mark the product "on sale" and to use `sale_price` 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 3rd party carriers in box packing algorithms to optimize shipping costs.
  - `height` (float): Height of the product in `unit`.
  - `length` (float): Length of the product in `unit`.
  - `unit` (enum): Either `in` (inches) or `cm` (centimeters). Possible values: `in`, `cm`. Default: `"in"`.
  - `width` (float): Width of the product in `unit`.
- `shipment_location` (string): ID of location from `/settings/shipping/locations`. If specified, shipping is calculated from this origin. 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.
  - `package_quantity` (int): Maximum package quantity when rule is applied.
  - `price` (currency): Shipping price when rule is applied.
  - `fee_type` (enum): Type of fee to apply in addition to `price`, either `fixed` or `percent`. Possible values: `fixed`, `percent`.
  - `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`.
  - `total_min` (currency): Minimum order subtotal for this rule to apply.
  - `total_max` (currency): Maximum order subtotal for this rule to apply.
  - `weight_min` (float): Minimum order item weight for this rule to apply.
  - `weight_max` (float): Maximum order item weight for this rule to apply.
  - `state` (string): Shipping state required for this rule to apply.
  - `zip` (string): Shipping zip/postal code required for this rule to apply.
  - `country` (string): Shipping country required for this rule to apply.
  - `account_group` (string): Customer group 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 store's default weight unit.
- `sku` (string): Stock keeping unit (SKU) used to track inventory in a warehouse.
- `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): Quantity of the product currently in stock (including all variants), based on the sum of the stock entries.
- `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`. Possible values: `discontinued`, `preorder`, `backorder`, `out_of_stock`, `in_stock`.
- `stock_tracking` (boolean): Set `true` to enable stock tracking this product.
- `subscription_interval` (enum): The default billing interval when this product is used as a subscription plan. Can be `monthly`, `yearly`, `weekly`, or `daily`. Possible values: `monthly`, `daily`, `weekly`, `yearly`.
- `subscription_interval_count` (int): Multiplier when combined with `subscription_interval`. For example, to make a subscription bill every 2 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.
- `summary` (string): A brief product summary.
- `tax_class` (string): Indicates the tax class for the product.
- `tax_code` (string): Product tax code for tracking with Avalara, TaxJar, etc.
- `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): Set `true` to generate variants for this product in the admin panel.
- `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.

### Example request

`POST /products`

**cURL**

```bash
$ curl https://api.swell.store/products \
  -u store-id:secret-key \
  -d name="T-Shirt" \
  -d price=99 \
  -d active=true \
  -d options[0][name]=Size \
  -d options[0][values][0][name]=Small \
  -d options[0][values][1][name]=Large
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.post('/products', {
  name: 'T-Shirt',
  price: 99.00,
  active: true,
  options: [
    {
      name: 'Size',
      values: [
        {
          name: 'Small',
        },
        {
          name: 'Large',
        },
      ],
    },
    {...},
  ],
});
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/products', [
  'name' => 'T-Shirt',
  'price' => 99.00,
  'active' => true,
  'options' => [
    [
      'name' => 'Size',
      'values' => [
        [
          'name' => 'Small',
        ],
        [
          'name' => 'Large',
        ],
      ],
    ],
    [...],
  ],
]);
```

### Example response

```json
{
  "id": "5ca24abb9c077817e5fe2b36",
  "active": true,
  "attributes": {},
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "delivery": "shipment",
  "name": "T-Shirt",
  "options": [
    {
      "id": "5ca24ab32599d4179c24a624",
      "name": "Size",
      "variant": true,
      "required": true,
      "values": [
        {
          "id": "5ca24ad59c077817e5fe2ba3",
          "name": "Small"
        },
        {
          "id": "5ca24ad59c077817e5fe2ba4",
          "name": "Medium"
        },
        {
          "id": "5ca24ad59c077817e5fe2ba5",
          "name": "Large"
        }
      ]
    }
  ],
  "price": 99.00,
  "slug": "swell-t-shirt",
  "type": "standard"
}
```


## Retrieve a product

Retrieve an existing product using the ID that was returned when created.

### Arguments

- `id` (objectId, required): The id of the product to retrieve.
- `expand` (string): Expanding link fields and child collections is performed using the expand argument.

  - For example, `expand=account` would return a related customer account if one exists.

  When the field represents a collection, you can specify the query limit.

  - For example, `expand=variants:10` would return up to 10 records of the variants collection.

  See [expanding ](https://developers.swell.is/backend-api/querying/expanding)for more details.
- `fields` (string): Return only the specified fields in the result. For example `fields=name,slug` would return only the fields `name` and `slug` in the response. Supports nested object and array fields using dot-notation.

  - For example, `items.product_id`. The category `id` is always returned.
- `include` (string): Include one or more arbitrary queries in the response, possibly related to the main query.

  See [including ](https://developers.swell.is/backend-api/querying/including)for more details.

### Example request

`GET /products/:id`

**cURL**

```bash
$ curl https://api.swell.store/products/5ca24abb9c077817e5fe2b36 \
  -u store-id:secret-key
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.get('/products/{id}', {
  id: '5ca24abb9c077817e5fe2b36'
});
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/products/{id}', [
  'id' => '5ca24abb9c077817e5fe2b36'
]);
```

### Example response

```json
{
  "id": "5ca24abb9c077817e5fe2b36",
  "active": true,
  "attributes": {},
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-02T00:26:23.399Z",
  "delivery": "shipment",
  "description": null,
  "images": [
    {
      "id": "5ca24abb9c077817e5fe2b37",
      "file": {
        "id": "5ca24abb9c077817e5fe2b38",
        "date_uploaded": "2019-04-02T00:26:23.399Z",
        "length": 66764,
        "md5": "99194f53bfdea832553e7fa8ae8fd80f",
        "content_type": "image/png",
        "url": "http://cdn.swell.store/test/5ca24abb9c077817e5fe2b36/99194f53bfdea832553e7fa8ae8fd80f",
        "width": 940,
        "height": 600
      }
    }
  ],
  "meta_description": null,
  "meta_title": null,
  "name": "T-Shirt",
  "options": [
    {
      "id": "5ca24ab32599d4179c24a624",
      "name": "Size",
      "variant": true,
      "required": true,
      "values": [
        {
          "id": "5ca24ad59c077817e5fe2ba3",
          "name": "Small"
        },
        {
          "id": "5ca24ad59c077817e5fe2ba4",
          "name": "Medium"
        },
        {
          "id": "5ca24ad59c077817e5fe2ba5",
          "name": "Large"
        }
      ]
    }
  ],
  "price": 9.99,
  "slug": "swell-t-shirt",
  "stock_level": 0,
  "stock_status": "available",
  "stock_tracking": true,
  "tags": [],
  "type": "standard"
}
```


## Update a product

Updates an existing product using the ID that was returned when created. Updating performs a merge operation. To explicitly override values such as arrays, use the `$set` operator.

### Arguments

- `id` (objectId, required): Unique identifier for the product.
- `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): 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).
    - `active` (boolean): 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 as 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).
    - `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): 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): 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: `∞`.
- `active` (boolean): Set `true` to make the product visible to customers in a storefront, otherwise it will be hidden.
- `attributes` (object): An object containing custom attribute key/value pairs. See [attributes](https://developers.swell.is/backend-api/attributes/the-attribute-model) for more details.
- `name` (string): Human-friendly name 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.
- `slug` (string): 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.
- `bundle` (boolean): Indicates whether the product is a bundle of other products.
- `bundle_items` (object): List of products sold as a bundle. Applicable only when `bundle=true`.
  - `product_id` (objectId): The id of the bundled product.
  - `quantity` (int): Quantity of the bundled product. Default: `1`.
  - `variant_id` (objectId): The id of the bundled variant, if applicable.
- `category_id` (objectId): Primary category, commonly used as a navigation anchor.
- `cost` (currency): Cost of goods (COGS) used to calculate gross margins.
- `cross_sells` (object): List of products to display as cross-sells on a shopping cart page.
  - `product_id` (objectId): The id of the cross-sell product.
  - `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`.
  - `discount_type` (string): Type of discount to apply: `fixed` or `percent`.
- `customizable` (boolean): Set `true` to enable custom options for this product in the admin panel.
- `description` (string): A long form description of the product. May have HTML or other markup.
- `images` (object): List of images depicting the bundle.
  - `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.
    - `data` (file): Set or overwrite file data. Use the following format when writing a file from binary data (for example an image): `data[$binary]=<base64 encoded binary daya>`.
    - `filename` (string): Optional file name.
- `meta_description` (string): Page description used for search engine optimization purposes.
- `meta_keywords` (string): Page keywords used for search engine optimization purposes.
- `meta_title` (string): Page title used to override product name in storefronts.
- `Options` (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.
  - `name` (string): Human-friendly name of the option.
  - `input_hint` (string): Some brief hint text to help the user understand this option.
  - `input_type` (string): Type of user input to display for this option in a storefront. Can be `text`, `textarea`, `select`, `multi_select`, `file` or `multi_file`. `select` is ideal for dropdown or radio selectors, and `multi_select` is ideal for checkboxes. A maximum of 10 files can be uploaded by the user, and there are no restrictions on file type.
  - `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 objectId): The 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.
  - `subscription` (boolean): Set `true` to indicate the option's values specify a subscription billing interval. In this case, option values must have a `subscription_interval` of `monthly`, `yearly`, `weekly` or `daily`.
  - `values` (object): List of possible values for this option.
    - `name` (string): Human-friendly name of the option value.
    - `description` (string): A brief description of the option value, intended for displaying to customers.
    - `images` (object): One or more images depicting the option value.
      - `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.
        - `data` (file): Set or overwrite file data. Use the following format when writing a file from binary data (for example an image): `data[$binary]=<base64 encoded binary daya>`.
        - `filename` (string): Optional file name.
    - `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` (string): When product `type=subscription`, this is the billing interval used when this option value is selected. Can be `monthly`, `yearly`, `weekly` or `daily`.
    - `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 2 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.
  - `variant` (boolean): Set `true` to generate variants including this option.
- `prices` (object): Set price rules to use when conditions match the customer's account group or product quantity in a cart.
  - `price` (currency): Set price to apply 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_inc` (int): Specifies a quantity multiple the product must be sold in.
- `quantity_min` (int): Minimum quantity of the product that can be sold at once.
- `sale` (boolean): Set `true` to mark the product "on sale" and to use `sale_price` 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 3rd party carriers in box packing algorithms to optimize shipping costs.
  - `height` (float): Height of the product in `unit`.
  - `length` (float): Length of the product in `unit`.
  - `unit` (string): Either `in` (inches) or `cm` (centimeters).
  - `width` (float): Width of the product in `unit`.
- `shipment_location` (string): ID of location from `/settings/shipping/locations`. If specified, shipping is calculated from this origin. Otherwise, the store 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` (object): Product shipping price rules to override default shipping rules.
  - `service` (string): 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` (string): 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 store's default weight unit.
- `sku` (string): Stock keeping unit (SKU) used to track inventory in a warehouse.
- `stock_tracking` (boolean): Set `true` to enable stock tracking this product.
- `subscription_interval` (string): 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 2 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.
- `tags` (array of string): List of arbitrary tags typically used as metadata to improve search results or associate custom behavior with a product.
- `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.
- `up_sells` (object): List of products to display as up-sells on a product detail page.
  - `product_id` (objectId): The id of the up-sell product.
- `variable` (boolean): Set `true` to generate variants for this product in the admin panel.

### Example request

**Update a product**

`PUT /products/:id`

**cURL**

```bash
$ curl https://api.swell.store/products/5ca24abb9c077817e5fe2b36 \
  -u store-id:secret-key \
  -d price=9.99 \
  -X PUT
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.put('/products/{id}', {
  id: '5ca24abb9c077817e5fe2b36',
  price: 19.98,
  // use $set to override values
  $set: {
    options: [
      ...
    ],
  },
});
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->put('/products/{id}', [
  'id' => '5ca24abb9c077817e5fe2b36',
  'price' => 19.98,
  // use $set to override values
  '$set' => [
    'options' => [
      ...
    ],
  ],
]);
```

### Example response

```json
{
  "id": "5ca24abb9c077817e5fe2b36",
  "active": true,
  "attributes": {},
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "delivery": "shipment",
  "description": null,
  "images": [
    {
      "id": "5ca24abb9c077817e5fe2b37",
      "file": {
        "id": "5ca24abb9c077817e5fe2b38",
        "date_uploaded": "2019-04-02T00:26:23.399Z",
        "length": 66764,
        "md5": "99194f53bfdea832553e7fa8ae8fd80f",
        "content_type": "image/png",
        "url": "http://cdn.swell.store/test/5ca24abb9c077817e5fe2b36/99194f53bfdea832553e7fa8ae8fd80f",
        "width": 940,
        "height": 600
      }
    }
  ],
  "meta_description": null,
  "meta_title": null,
  "name": "T-Shirt",
  "options": [
    {
      "id": "5ca24ab32599d4179c24a624",
      "name": "Size",
      "variant": true,
      "required": true,
      "values": [
        {
          "id": "5ca24ad59c077817e5fe2ba3",
          "name": "Small"
        },
        {
          "id": "5ca24ad59c077817e5fe2ba4",
          "name": "Medium"
        },
        {
          "id": "5ca24ad59c077817e5fe2ba5",
          "name": "Large"
        }
      ]
    }
  ],
  "price": 9.99,
  "slug": "swell-t-shirt",
  "stock_level": 0,
  "stock_status": "available",
  "stock_tracking": true,
  "tags": [],
  "type": "standard"
}
```


## List all products

Return a list of products.

### Arguments

- `categories` (objectId): Supports filtering a single by a single top-level category with `id`, or also supports an array of categories and their sub-categories. For an array, notate category IDs within brackets: `categories: [ ...ids ]`.
- `expand` (string): Expand link fields and child collections by using the expand argument.

  - For example, `expand=account` would return a related customer account if one exists.

  When the field represents a collection, you can specify the query limit.

  - For example, `expand=variants:10` would return up to 10 records of the variants collection.

  See [expanding](https://developers.swell.is/backend-api/querying/expanding) for more details.
- `fields` (string): Returns only the specified fields in the result.

  - For example `fields=name,slug` would return only the fields `name` and `slug` in the response.

  Supports nested object and array fields using dot-notation.

  - For example, `items.product_id`. The product `id` is always returned.
- `include` (object): Include one or more arbitrary queries in the response which are potentially related to the main query.

  See [including](https://developers.swell.is/backend-api/querying/including) for more details.
- `limit` (int): Limit the number of records returned, ranging between `1` and `1000`. Defaults to `15`. Default: `15`.
- `page` (int): The page number of results to return given the specified or default `limit`.
- `search` (string): A text search is performed using the search argument. Searchable fields are defined by the model.

  - For example, `search=red` would return records containing the word "red" anywhere in the defined text fields.

  See [searching](https://developers.swell.is/backend-api/querying/searching) for more details.
- `sort` (string): Expression to sort results by using a format similar to a SQL sort statement.

  - For example, `sort=name asc` would return records sorted by name ascending.

  See [sorting](https://developers.swell.is/backend-api/querying/sorting) for more details.
- `where` (object): An object with criteria to filter the result.

  - For example, `active=true` would return records containing a field `active` with the value `true`.

  It's also possible to use query operators, for example, `$eq`, `$ne`, `$gt`, and more.

  See [querying](https://developers.swell.is/backend-api/querying) for more details.

### Example request

`GET /products`

**cURL**

```bash
$ curl https://api.swell.store/products?where[active]=true&limit=25&page=1 \
  -u store-id:secret-key \
  -G
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.get('/products', {
  where: { active: true },
  limit: 25,
  page: 1,
});
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/products', [
  'where' => [ 'active' => true ],
  'limit' => 25,
  'page' => 1,
]);
```

### Example response

```json
{
  "count": 51,
  "results": [
    {
      "id": "5ca24abb9c077817e5fe2b36",
      "active": true,
      "attributes": {},
      "currency": "USD",
      "date_created": "2019-04-01T00:00:00.000Z",
      "date_updated": "2019-04-01T00:00:00.000Z",
      "delivery": "shipment",
      "description": null,
      "images": [],
      "meta_description": null,
      "meta_title": null,
      "name": "T-Shirt",
      "options": [],
      "price": 9.99,
      "slug": "swell-t-shirt",
      "stock_level": 0,
      "stock_status": "available",
      "stock_tracking": true,
      "tags": [],
      "type": "standard"
    },
    {...},
    {...}
  ],
  "page": 1,
  "page_count": 3,
  "limit": 25,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "3": {
      "start": 51,
      "end": 51
    }
  }
}
```


## Delete a product

Deleting a product that has already been sold will break any links that exist within orders. We recommend only deleting products that have not yet been sold to a customer.

> **Warning:** When deleting a record that has child collections such as `variants` and `stock`, the contents of those collections are also deleted.

### Arguments

- `id` (objectId, required): The id of the product you wish to delete.

### Example request

`DELETE /products/:id`

**cURL**

```bash
$ curl https://api.swell.store/products/5ca24abb9c077817e5fe2b36 \
  -u store-id:secret-key \
  -X DELETE
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.delete('/products/{id}', {
  id: '5ca24abb9c077817e5fe2b36',
});
```

**PHP**

```php
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->delete('/products/{id}', [
  'id' => '5ca24abb9c077817e5fe2b36',
]);
```

### Example response

```json
{
  "id": "5ca24abb9c077817e5fe2b36",
  "active": true,
  "attributes": {},
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "delivery": "shipment",
  "description": null,
  "images": [],
  "meta_description": null,
  "meta_title": null,
  "name": "T-Shirt",
  "options": [],
  "price": 9.99,
  "slug": "swell-t-shirt",
  "stock_level": 0,
  "stock_status": "available",
  "stock_tracking": true,
  "tags": [],
  "type": "standard"
}
```