# Variants

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

Product variants represent unique variations of a product that support stock tracking. Each variant is a combination of one or more options, for example, Size or Color. Variants are children of [products](https://developers.swell.is/backend-api/products).

## The variant model

### Fields

- `id` (objectId, auto): Unique identifier for the variant.
- `name` (string, required): Human-friendly name of the variant. Defaults to the combined name of all options, for example "Blue, Large" in the case of 2 options; color and size.
- `parent_id` (objectId, required): ID of the parent product.
- `active` (boolean): An active variant is visible to customers in a storefront. Otherwise it will be hidden from view. Default: `false`.
- `archived` (boolean): A variant is automatically archived when it has been sold in the past and product options are changed in a way that would cause the variant to be removed.
- `attributes` (object): An object containing custom attribute values. Overrides product attributes. See [attributes](https://developers.swell.is/frontend-api/attributes) for more details.
- `code` (string): Unique code to identify the gift card variant.
- `cost` (currency): Cost of goods used to calculate gross margins. Overrides parent product `cost`.
- `currency` (string): Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase. Defaults to store's base currency.
- `date_created` (date, auto): Date and time the variant was created.
- `date_updated` (date, auto): Date and time the variant was last updated.
- `images` (array of object): List of images depicting the variant.
  - `id` (objectId, auto): Unique identifier for the object.
  - `caption` (string): A brief description of the image.
  - `file` (object): An object representing the image file.
    - `id` (objectId): Unique identifier for the file.
    - `content_type` (string): MIME content type of the file.
    - `data` (filedata): A reference to the raw file data.
    - `date_uploaded` (date): Date the file was uploaded.
    - `filename` (string): Optional file name.
    - `height` (int): Image height in pixels, if applicable.
    - `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.
    - `url` (string): A public URL to reference the file. Updated automatically if file content changes.
    - `width` (int): Image width in pixels, if applicable.
    - `private` (boolean): Indicates the image is not visible to customers.
    - `metadata` (object): Arbitrary image data, typically used to store custom values. See Frontend API for more details.
- `option_value_ids` (array of child_scalar): List of option value IDs that constitute the variant.
- `orig_price` (currency): Reflects the non-sale price of the product
- `parent` (Product): Expandable link to the parent product.
- `price` (currency): List price used by default when `sale=false` or `sale_price` is not defined. Overrides parent product `price`.
- `prices` (array of object): Price rules to override `price` and `sale_price` when conditions match quantity or account group in a cart. Overrides parent product `prices`.
  - `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.
  - `discount_percent` (float)
- `purchase_options` (object): Purchase options available for the product variant.
  - `standard` (object): Designates purchase option as a one-time purchase.
    - `price` (currency): List price used by default when `sale=false` or `sale_price` is not defined. Overrides product price.
    - `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.
      - `discount_percent` (float)
    - `orig_price` (currency)
- `sale` (boolean): Indicates the variant is on sale and`sale_price` is used by default when the product is added to a cart. Overrides parent product `sale`.
- `sale_price` (currency): Sale price used by default when `sale=true`, overriding `price`. Overrides parent product `sale_price`.
- `shipment_weight` (float): If specified, shipping is calculated based on this shipping weight. Otherwise, it will assume 1 lb/oz/kg depending on your default weight unit. Overrides parent product `shipment_weight`.
- `sku` (string): Stock keeping unit (SKU) used to track inventory in a warehouse.
- `stock` (Stock): Expandable list of stock adjustments for the variant.
- `stock_level` (int): Current in-stock quantity of the variant, based on the sum of [stock](https://developers.swell.is/backend-api/stock) entries.
- `stock_level_in_locations` (int): Total stock level of the variant across inventory locations.
- `stock_locations` (object): Stock distributed over inventory locations, if multi-location inventory is enabled.
- `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.

### Example response

```json
{
  "id": "60f199509111e70000000067",
  "name": "Medium",
  "parent_id": "60f199509111e70000000069",
  "active": true,
  "archived": false,
  "attributes": {
    "example": true
  },
  "currency": "USD",
  "date_created": "2021-07-16T14:36:00.333Z",
  "date_updated": "2021-07-16T14:36:00.333Z",
  "images": [
    {
      "id": "5ca24abb9c077817e5fe2b37",
      "caption": "Just a variant",
      "file": {
        "id": "5ca24abb9c077817e5fe2b38",
        "length": 66764,
        "md5": "99194f53bfdea832553e7fa8ae8fd80f",
        "content_type": "image/png",
        "url": "http://cdn.swell.store/test/5ca24abb9c077817e5fe2b36/99194f53bfdea832553e7fa8ae8fd80f",
        "width": 940,
        "height": 600
      }
    }
  ],
  "option_value_ids": [
    "59764b54e68ba2330390319a"
  ],
  "price": 18.99,
  "sale": false,
  "sale_price": null,
  "sku": "EX2001",
  "stock_level": 6
}
```


## Create a variant

Create a new product variant. Normally, variants are automatically created when product options are set.

### Arguments

- `name` (string, required): Human-friendly name of the variant. Defaults to the combined name of all options, for example, "Blue, Large" in the case of 2 options; color and size.
- `parent_id` (objectId, required): The id of the parent product.
- `attributes` (object): An object containing custom attribute values. Overrides product attributes. See [attributes](https://developers.swell.is/frontend-api/attributes) for more details.
- `option_value_ids` (array of objectId): List of option value IDs that constitute the variant.
- `price` (currency): List price used by default when `sale=false` or `sale_price` is not defined. Overrides product price.
- `active` (boolean): An active variant is visible to customers in a storefront. Otherwise, it will be hidden from view.
- `archived` (boolean): A variant is automatically archived when it has been sold in the past and product options are changed in a way that would cause the variant to be removed.
- `cost` (currency): Cost of goods used to calculate gross margins. Overrides product cost.
- `images` (array of object): List of images depicting the variant.
  - `id` (objectId, auto): Unique identifier for the object.
  - `caption` (string): A brief description of the image.
  - `file` (object): An object representing the image file.
    - `id` (objectId): Unique identifier for the file.
    - `content_type` (string): MIME content type of the file.
    - `data` (filedata): data
    - `date_uploaded` (date): Date the file was uploaded.
    - `filename` (string): Optional file name.
    - `height` (int): Image height in pixels, if applicable.
    - `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.
    - `url` (string): A public URL to reference the file. Updated automatically if file content changes.
    - `width` (int): Image width in pixels, if applicable.
    - `private` (boolean): Indicates the image is not visible to customers.
    - `metadata` (object): Arbitrary image data, typically used to store custom values. See Frontend API for more details.
- `prices` (array of object): Price rules to override `price` and `sale_price` when conditions match quantity or account group in a cart. Overrides product prices
  - `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.
- `sale` (boolean): Indicates the variant is on sale and `sale_price` is used by default when the product is added to a cart. Overrides product sale.
- `sale_price` (currency): Sale price used by default when `sale=true`, overriding `price`. Overrides product sale price.
- `shipment_weight` (float): If specified, shipping is calculated based on this shipping weight. Otherwise, it will assume 1 lb/oz/kg depending on your default weight unit. Overrides product shipping weight.
- `sku` (string): Stock keeping unit (SKU) used to track inventory in a warehouse.

### Example request

`POST /products:variants`

**cURL**

```bash
$ curl https://api.swell.store/products:variants \
  -u store-id:secret-key \
  -d parent_id=5ca24abb9c077817e5fe2b36
  -d name="Blue, Small"
```

**Node**

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

await swell.post('/products:variants', {
  parent_id: '5ca24abb9c077817e5fe2b36',
  name: 'Blue, Small',
});
```

**PHP**

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

$swell->post('/products:variants', [
  'parent_id' => '5ca24abb9c077817e5fe2b36',
  'name' => 'Blue, Small',
]);
```

### Example response

```json
{
  "id": "5c8fb5e1ed2faf8c79da492a",
  "parent_id": "5ca24abb9c077817e5fe2b36",
  "name": "Blue, Small",
  "active": true,
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z"
}
```


## Retrieve a variant

Retrieve an existing variant using the id that was returned when created.

### Arguments

- `id` (objectId, required): The id of the variant 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 variant `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:variants/:id`

**cURL**

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

**Node**

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

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

**PHP**

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

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

### Example response

```json
{
  "id": "5c8fb5e1ed2faf8c79da492a",
  "parent_id": "5ca24abb9c077817e5fe2b36",
  "name": "Blue, Small",
  "active": true,
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z"
  "date_updated": "2019-04-01T00:00:00.000Z",
}
```


## Update a variant

Update 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 variant.
- `parent_id` (objectId): The id of the parent product.
- `active` (boolean): An active variant is visible to customers in a storefront, otherwise it will be hidden from view.
- `attributes` (object): An object containing custom attribute values. Overrides product attributes. See [attributes](https://developers.swell.is/frontend-api/attributes) for more details.
- `name` (string): Human-friendly name of the variant. Defaults to the combined name of all options, for example, "Blue, Large" in the case of 2 options; color and size.
- `price` (currency): List price used by default when `sale=false` or `sale_price` is not defined. Overrides product price.
- `archived` (boolean): A variant is automatically archived when it has been sold in the past and product options are changed in a way that would cause the variant to be removed.
- `cost` (currency): Cost of goods used to calculate gross margins. Overrides product cost.
- `images` (object): List of images depicting the variant.
  - `caption` (string): A brief description of the image.
  - `file` (object): An object representing the image file.
    - `data` (file): A reference to the raw file data.
    - `filename` (string): Optional file name.
- `prices` (array of object): Price rules to override `price` and `sale_price` when conditions match quantity or account group in a cart. Overrides product prices.
  - `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.
- `sale` (boolean): Indicates the variant is on sale and `sale_price` is used by default when the product is added to a cart. Overrides product sale.
- `sale_price` (currency): Sale price used by default when `sale=true`, overriding `price`. Overrides product sale price.
- `shipment_weight` (float): If specified, shipping is calculated based on this shipping weight. Otherwise it will assume 1 lb/oz/kg depending on your default weight unit. Overrides product shipping weight.
- `sku` (string): Stock keeping unit (SKU) used to track inventory in a warehouse.

### Example request

`PUT /products:variants/:id`

**cURL**

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

**Node**

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

await swell.put('/products:variants/{id}', {
  id: '5c8fb5e1ed2faf8c79da492a',
  price: 19.98,
});
```

**PHP**

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

$swell->put('/products:variants/{id}', [
  'id' => '5c8fb5e1ed2faf8c79da492a',
  'price' => 19.98,
]);
```

### Example response

```json
{
  "id": "5c8fb5e1ed2faf8c79da492a",
  "parent_id": "5ca24abb9c077817e5fe2b36",
  "name": "Blue, Small",
  "active": true,
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "price": 19.98
}
```


## List all variants

Return a list of product variants.

### Arguments

- `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:variants`

**cURL**

```bash
$ curl https://api.swell.store/products:variants?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:variants', {
  where: { active: true },
  limit: 25,
  page: 1,
});
```

**PHP**

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

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

### Example response

```json
{
  "count": 15,
  "results": [
    {
      "id": "5c8fb5e1ed2faf8c79da492a",
      "parent_id": "5ca24abb9c077817e5fe2b36",
      "name": "Blue, Small",
      "active": true,
      "currency": "USD",
      "date_created": "2019-04-01T00:00:00.000Z",
      "date_updated": "2019-04-01T00:00:00.000Z",
      "price": 19.98
    },
    {...},
    {...}
  ],
  "page": 1,
  "page_count": 1,
  "limit": 25
}
```


## Delete a variant

Delete a variant. Try to avoid deleting variants that have been sold to a customer, as the link to existing orders will be broken.

### Arguments

- `id` (objectId, required): The id of the variant to delete.

### Example request

`DELETE /products:variants/:id`

**cURL**

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

**Node**

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

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

**PHP**

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

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

### Example response

```json
{
  "id": "5c8fb5e1ed2faf8c79da492a",
  "parent_id": "5ca24abb9c077817e5fe2b36",
  "name": "Blue, Small",
  "active": true,
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "price": 19.98
}
```