Backend API
Create a new product.
A product's attributes object is keyed by each attribute's id, so the attribute must exist before a product can reference it. An attribute's id defaults to its name in underscored form and cannot be changed afterwards.
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');
// Create the attribute first. Its id is derived from the name,
// so this attribute is referenced as `material`.
await swell.post('/attributes', {
name: 'Material',
type: 'select',
values: ['Silver', 'Gold', 'Titanium'],
visible: true,
filterable: true
});
// Create a product that uses it, keyed by the attribute id
await swell.post('/products', {
name: 'Signet Ring',
price: 149.00,
active: true,
attributes: {
material: 'Silver'
}
});
// A value can also be an array
await swell.post('/products', {
name: 'Mixed Metal Bangle',
price: 89.00,
active: true,
attributes: {
material: ['Silver', 'Gold']
}
});Variant attributes are created a different way. An option with variant set to true and at least one value creates or updates the matching attribute record automatically, and fills in the product's attributes from the option values.
Arguments
Human-friendly name of the product.
List price used when sale=false or sale_price is not defined. This value is intended for use via the frontend. See the purchase_options array to manage a product's price.
An object containing custom attribute key/value pairs. See attributes for more details.
Lowercase, hyphenated identifier typically used in URLs. When creating a product, a slug will be generated automatically from the name. Maximum length of 1,000 characters.
Configuration of one or more purchase options for the product. Can be standard for one-time purchases or subscription for a subscription plan. Products can support both purchase options simultaneously.
Designates purchase option as a one-time purchase.
ID of the purchase option.
The name of the purchase option.
A long-form description of the product. May contain HTML or other markup languages.
Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
List price used when sale=false or sale_price is not defined.
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.
Array of account groups that are eligible to access the purchase option within the storefront.
Designates purchase option as a subscription plan.
ID of the subscription plan purchase option.
Name of the subscription plan purchase option.
A long-form description of the purchase option. May contain HTML or other markup languages.
Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.
Array of account_group names for which the purchase option is available.
Array defining subscription plans and their respective configurations.
ID of the purchase option subscription plan.
Name of the subscription plan.
A long-form description of the subscription plan. May contain HTML or other markup languages.
Indicates whether the subscription plan is available for customers to purchase. Inactive products will not be returned on the Frontend.
List price used when sale=false or sale_price is not defined.
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.
Determines the billing schedule for the subscription plan.
Subscription plan billing interval. Can be daily, weekly, monthly, or yearly.
Possible enum values:
Multiplier for billing interval. For example, to make the billing cycle once every two weeks, set interval=weekly and interval_count=2.
Specifies a limit to the number of billing cycles for the subscription plan. For example, limit=10 would stop billing the customer after the tenth billing cycle.
Set true to make the product visible to customers in a storefront, otherwise it will be hidden.
Indicates whether the product is a bundle of other products.
List of products sold as a bundle. Applicable only when bundle=true.
ID of the bundled product.
ID of the bundled product.
Expandable link to the bundled product.
Quantity of the bundled product. Defaults to 1.
ID of the bundled variant, if applicable.
Expandable link to the bundled product variant, if applicable.
Expandable link to all related product categories.
Expandable link to the primary category.
Primary category, commonly used as a navigation anchor.
Index of categories used for fast lookup operations.
Index of category IDs and their respective sort positions.
Unique code to identify the gift card product.
Cost of goods (COGS) that is used to calculate gross margins.
List of products to display as cross-sells on a shopping cart page.
Unique identifier for the cross-sell object.
ID of the cross-sell product.
Expandable link to the cross-sell product.
Discount to apply as a fixed amount. Applicable only when discount_type=fixed.
Discount to apply as a percentage. Applicable only when discount_type=percent.
Type of discount to apply, either fixed or percent.
Possible enum values:
Three-letter ISO currency code in uppercase. Defaults to your store's base currency.
Set true to enable custom options for this product in the admin panel.
Method of fulfillment automatically assigned based on type:
- shipment means the product will be physically shipped to a customer.
- subscription means the product will be fulfilled as a subscription when an order is placed. giftcard delivery means the product will be fulfilled as a gift card when an order is placed.
- null means the product will not be fulfilled by one of the above methods.
Note: A bundle has its child products fulfilled individually; each product in the bundle must have its own fulfillment method.
Possible enum values:
A long form description of the product. May have HTML or other markup.
Indicates whether the product has been discontinued.
List of images depicting the bundle.
Unique identifier for the image.
A brief description of the image, intended for display as a caption or alt text.
An object representing the image's source file.
Unique identifier for the file.
Date the file was uploaded.
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.
Optional file name.
MIME content type of the file.
A set of arbitrary data that is typically used to store custom values.
Set or overwrite file data. Use the following format when writing a file from binary data (for example an image): data[$binary]=<base64 encoded binary data>.
Indicates whether the file is private.
A public URL to reference the file. Updated automatically if file content changes.
Image width in pixels, if applicable.
Image height in pixels, if applicable.
Page description used for search engine optimization purposes.
Page keywords used for search engine optimization purposes.
Page title used to override product name in storefronts.
Set price rules to use when conditions match the customer's account group or product quantity in a cart.
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.
Specifies a quantified multiple the product must be sold in.
Minimum quantity of the product that can be sold at once.
Array of related product IDs.
Set true to mark the product "on sale" and to use sale_price when the product is added to a cart.
Sale price used to override list price when sale=true.
Product dimensions when packed for shipping. Typically used by 3rd party carriers in box packing algorithms to optimize shipping costs.
Height of the product in unit.
Length of the product in unit.
Either in (inches) or cm (centimeters).
Possible enum values:
Width of the product in unit.
ID of location from /settings/shipping/locations. If specified, shipping is calculated from this origin. Otherwise, the store's default location will be used.
If specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package.
Product shipping price rules to override default shipping rules.
Shipping service required for this rule to apply.
Maximum package quantity when rule is applied.
Shipping price when rule is applied.
Type of fee to apply in addition to price, either fixed or percent.
Possible enum values:
Fixed amount to add when rule is applied. Only applicable when fee_type=fixed.
Percentage of the shipping price to add when rule is applied. Only applicable when fee_type=percent.
Minimum order subtotal for this rule to apply.
Maximum order subtotal for this rule to apply.
Minimum order item weight for this rule to apply.
Maximum order item weight for this rule to apply.
Shipping state required for this rule to apply.
Shipping zip/postal code required for this rule to apply.
Shipping country required for this rule to apply.
Customer group required for this rule to apply.
If specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg — depending on store's default weight unit.
Stock keeping unit (SKU) used to track inventory in a warehouse.
Expandable list of stock adjustments for the product.
Indicates whether the product can be backordered if out of stock.
Quantity of the product currently in stock (including all variants), based on the sum of the stock entries.
Indicates whether the product can be purchased as a preorder.
Indicates whether the product's stock is purchasable.
String indicating the product's stock status for the purpose of ordering. When stock_purchasable=true, an order can be placed for this product regardless of current stock status, otherwise an order submission will be blocked unless stock status is available, preorder ,or backorder.
Possible enum values:
Set true to enable stock tracking this product.
The default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly, or daily.
Possible enum values:
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.
A brief product summary.
Indicates the tax class for the product.
Product tax code for tracking with Avalara, TaxJar, etc.
List of products to display as up-sells on a product detail page.
Unique identifier for the up-sell.
ID of the up-sell product.
Expandable link to the up-sell product.
Set true to generate variants for this product in the admin panel.
Expandable list of variants representing unique variations of the product. Each variant is a combination of one or more options. For example, Size and Color.
Indicates whether the product is virtual.
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');
await swell.post('/products', {
name: 'T-Shirt',
price: 99.00,
active: true,
options: [
{
name: 'Size',
values: [
{
name: 'Small',
},
{
name: 'Large',
},
],
},
{...},
],
});
Response
{
"id": "5ca24abb9c077817e5fe2b36",
"active": true,
"attributes": {},
"currency": "USD",
"date_created": "2019-04-01T00:00:00.000Z",
"delivery": "shipment",
"name": "T-Shirt",
"options": [
{
"id": "5ca24ab32599d4179c24a624",
"name": "Size",
"variant": true,
"required": true,
"values": [
{
"id": "5ca24ad59c077817e5fe2ba3",
"name": "Small"
},
{
"id": "5ca24ad59c077817e5fe2ba4",
"name": "Medium"
},
{
"id": "5ca24ad59c077817e5fe2ba5",
"name": "Large"
}
]
}
],
"price": 99.00,
"slug": "swell-t-shirt",
"type": "standard"
}