# Create a variant

Source: https://developers.swell.is/backend-api/variants/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"
}
```