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.

The variant model

Fields

id

objectIdauto

Unique identifier for the variant.

name

stringrequired

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

objectIdrequired

ID of the parent product.

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.

attributes

object

An object containing custom attribute values. Overrides product attributes. See 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 in uppercase. Defaults to store's base currency.

date_created

dateauto

Date and time the variant was created.

date_updated

dateauto

Date and time the variant was last updated.

images

array of object

List of images depicting the variant.

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 objectrequired

Price rules to override price and sale_price when conditions match quantity or account group in a cart. Overrides parent product prices.

purchase_options

object

Purchase options available for the product variant.

sale

boolean

Indicates the variant is on sale andsale_price is used by default when the product is added to a cart. Overrides parent product sale.

sale_price

currencyrequired

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 entries.

subscription_interval

enum

The default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly or daily.

Possible enum values:

monthlydailyweeklyyearly

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.

The product variant model

{
  "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. If you wish to generate your own unique ID for the options or variant, it must use BSON ObjectID format for compatibility.

Arguments

name

stringrequired

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

objectIdrequired

The id of the parent product.

attributes

object

An object containing custom attribute values. Overrides product attributes. See 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.

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

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.

POST/product:variants

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

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

Response

{
  "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

objectIdrequired

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 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 for more details.

GET/product:variants/:id

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

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

Response

{
  "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

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 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.

PUT/products:variants/:id

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

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

Response

{
  "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 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 for more details.

limit

int

Limit the number of records returned, ranging between 1 and 1000. Defaults to 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 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 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 for more details.

GET/products:variants

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

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

Response

{
  "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,
  "pages": {
    "1": {
      "start": 1,
      "end": 15
    }
  }
}

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

objectIdrequired

The id of the variant to delete.

DELETE/products:variants/:id

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

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

Response

{
  "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
}

← Back: Products Next: Stock →

Variants

The variant model

Fields

id

name

parent_id

active

archived

attributes

code

cost

currency

date_created

date_updated

images

id

caption

file

file.id

file.content_type

file.data

file.date_uploaded

file.filename

file.height

file.length

file.md5

file.url

file.width

file.private

file.metadata

option_value_ids

orig_price

parent

price

prices

price

account_group

quantity_max

quantity_min

discount_percent

purchase_options

purchase_options.standard

standard.price

standard.sale

standard.sale_price

standard.prices

price

account_group

quantity_max

quantity_min

discount_percent

standard.orig_price

sale

sale_price

shipment_weight

sku

stock

stock_level

subscription_interval

subscription_interval_count

subscription_trial_days

The product variant model

Create a variant

Arguments

name

parent_id

attributes

option_value_ids

price

active

archived

cost

images

.id

.caption

.file

file.id

file.content_type

file.data

file.date_uploaded