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

idobjectIdauto

Unique identifier for the variant.

namestringrequired

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_idobjectIdrequired

ID of the parent product.

activeboolean

An active variant is visible to customers in a storefront. Otherwise it will be hidden from view.

archivedboolean

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.

attributesobject

An object containing custom attribute values. Overrides product attributes. See attributes for more details.

codestring

Unique code to identify the gift card variant.

costcurrency

Cost of goods used to calculate gross margins. Overrides parent product cost.

currencystring

Three-letter ISO currency code in uppercase. Defaults to store's base currency.

date_createddateauto

Date and time the variant was created.

date_updateddateauto

Date and time the variant was last updated.

imagesarray of objectrequired

List of images depicting the variant.

option_value_idsarray of child_scalar

List of option value IDs that constitute the variant.

parentProduct

Expandable link to the parent product.

pricecurrency

List price used by default when sale=false or sale_price is not defined. Overrides parent product price.

pricesarray 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_optionsobject

Purchase options available for the product variant.

saleboolean

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_pricecurrencyrequired

Sale price used by default when sale=true, overriding price. Overrides parent product sale_price.

shipment_weightfloat

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.

skustring

Stock keeping unit (SKU) used to track inventory in a warehouse.

stockStock

Expandable list of stock adjustments for the variant.

stock_levelint

Current in-stock quantity of the variant, based on the sum of stock entries.

subscription_intervalenum

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

subscription_interval_countint

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_daysint

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 variant. Normally, variants are automatically created when product options are set.

Arguments

namestringrequired

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_idobjectIdrequired

The id of the parent product.

attributesobject

An object containing custom attribute values. Overrides product attributes. See attributes for more details.

option_value_idsarray of objectId

List of option value IDs that constitute the variant.

pricecurrency

List price used by default when sale=false or sale_price is not defined. Overrides product price.

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

idobjectIdrequired

The id of the variant to retrieve.

expandstring

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.

fieldsstring

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.

includestring

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

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

idobjectId

Unique identifier for the variant.

parent_idobjectId

The id of the parent product.

activeboolean

An active variant is visible to customers in a storefront, otherwise it will be hidden from view.

attributesobject

An object containing custom attribute values. Overrides product attributes. See attributes for more details.

namestring

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.

pricecurrency

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

expandstring

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.

fieldsstring

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.

includeobject

Include one or more arbitrary queries in the response which are potentially related to the main query.

See including for more details.

limitint

Limit the number of records returned, ranging between 1 and 1000. Defaults to 15.

pageint

The page number of results to return given the specified or default limit.

searchstring

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.

sortstring

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.

whereobject

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

idobjectIdrequired

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: ProductsNext: Stock →

Filter

What would you like to search for?

Variants

The variant model

Fields

The product variant model

Create a variant

Arguments

Response

Retrieve a variant

Arguments

Response

Update a variant

Arguments

Response

List all variants

Arguments

Response

Delete a variant

Arguments

Response