Filter
What would you like to search for?
Backend API
Fields
Unique identifier for the variant.
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.
ID of the parent product.
An active variant is visible to customers in a storefront. Otherwise it will be hidden from view.
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.
An object containing custom attribute values. Overrides product attributes. See attributes for more details.
Unique code to identify the gift card variant.
Cost of goods used to calculate gross margins. Overrides parent product cost.
Three-letter ISO currency code in uppercase. Defaults to store's base currency.
Date and time the variant was created.
Date and time the variant was last updated.
List of images depicting the variant.
Unique identifier for the object.
A brief description of the image.
An object representing the image file.
Unique identifier for the file.
MIME content type of the file.
A reference to the raw file data.
Date the file was uploaded.
Optional file name.
Image height in pixels, if applicable.
Size of the file in bytes.
An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.
A public URL to reference the file. Updated automatically if file content changes.
Image width in pixels, if applicable.
Indicates the image is not visible to customers.
Arbitrary image data, typically used to store custom values. See Frontend API for more details.
List of option value IDs that constitute the variant.
Expandable link to the parent product.
List price used by default when sale=false or sale_price is not defined. Overrides parent product price.
Price rules to override price and sale_price when conditions match quantity or account group in a cart. Overrides parent product prices.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
Purchase options available for the product variant.
Designates purchase option as a one-time purchase.
List price used by default when sale=false or sale_price is not defined. Overrides product price.
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 used by default when sale=true, overriding price. Overrides product sale price.
Price rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
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 used by default when sale=true, overriding price. Overrides parent product sale_price.
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.
Stock keeping unit (SKU) used to track inventory in a warehouse.
Expandable list of stock adjustments for the variant.
Current in-stock quantity of the variant, based on the sum of stock entries.
The default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly or daily.
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.
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 new variant. Normally, variants are automatically created when product options are set.
Arguments
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.
The id of the parent product.
An object containing custom attribute values. Overrides product attributes. See attributes for more details.
List of option value IDs that constitute the variant.
List price used by default when sale=false or sale_price is not defined. Overrides product price.
An active variant is visible to customers in a storefront. Otherwise, it will be hidden from view.
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 of goods used to calculate gross margins. Overrides product cost.
List of images depicting the variant.
A brief description of the image.
An object representing the image file.
Price rules to override price and sale_price when conditions match quantity or account group in a cart. Overrides product prices
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
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 used by default when sale=true, overriding price. Overrides product sale price.
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.
Stock keeping unit (SKU) used to track inventory in a warehouse.
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 an existing variant using the id that was returned when created.
Arguments
The id of the variant to retrieve.
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.
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 one or more arbitrary queries in the response, possibly related to the main query.
See including for more details.
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 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
Unique identifier for the variant.
The id of the parent product.
An active variant is visible to customers in a storefront, otherwise it will be hidden from view.
An object containing custom attribute values. Overrides product attributes. See attributes for more details.
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.
List price used by default when sale=false or sale_price is not defined. Overrides product price.
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 of goods used to calculate gross margins. Overrides product cost.
List of images depicting the variant.
A brief description of the image.
An object representing the image file.
A reference to the raw file data.
Optional file name.
Price rules to override price and sale_price when conditions match quantity or account group in a cart. Overrides product prices.
Price applied when conditions are met.
Customer account group as a condition to apply price.
Maximum quantity as a condition to apply price.
Minimum quantity as a condition to apply price.
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 used by default when sale=true, overriding price. Overrides product sale price.
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.
Stock keeping unit (SKU) used to track inventory in a warehouse.
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
}
Return a list of product variants.
Arguments
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.
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 one or more arbitrary queries in the response which are potentially related to the main query.
See including for more details.
Limit the number of records returned, ranging between 1 and 1000. Defaults to 15.
The page number of results to return given the specified or default limit.
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.
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.
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.
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. Try to avoid deleting variants that have been sold to a customer, as the link to existing orders will be broken.
Arguments
The id of the variant to delete.
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
}