Backend API

Products represent items that can be sold to a customer, either as one-off sales or as subscriptions. For more complex subscription products and when physical items are involved, it's recommended to create a subscription plan.

Fields

idobjectId

Unique identifier for the product.

namestringrequired

Human-friendly name of the product.

activeboolean

Indicates whether the product is active and available in the storefront.

purchase_optionsobject

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.

attributesobject

An object containing custom attribute key/value pairs.

bundleboolean

Indicates whether the product is a bundle of other products.

bundle_itemsarray of object

List of products sold as a bundle. Applicable only when bundle=true.

categoryCategory

Expandable link to the primary category.

category_idobjectId

Primary category, commonly used as a navigation anchor.

categoriesCategory

Expandable link to all related product categories.

category_indexobject

Index of categories used for fast lookup operations.

codestring

Unique code to identify the gift card product.

costcurrency

Cost of goods (COGS) used to calculate gross margins.

cross_sellsarray of object

List of products to display as cross-sells on a shopping cart page.

currencystring

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

customizableboolean

Indicates whether the product has custom options enabled.

date_createddateauto

Date and time the product was created.

date_updateddateauto

Date and time the product was last updated.

deliveryenumauto

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.

descriptionstring

A long-form description of the product. May contain HTML or other markup languages.

discontinuedboolean

Indicates whether the product has been discontinued.

imagesarray of object

List of images depicting the bundle.

meta_titlestring

Page title used to override product name in storefronts.

meta_keywordsstring

Page keywords used for search engine optimization purposes.

meta_descriptionstring

Page description used for search engine optimization purposes.

optionsarray of object

Options that allow for variations of the base product. If the option is part of a variant or required=true, an option value must be set for the product to be added to a cart.

orig_pricecurrency

Reflects the non-sale price of the product

pricecurrency

List price used when sale=false or sale_price is not defined.

pricesarray of price

Price rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.

quantity_minint

Minimum quantity of the product that can be sold at once.

quantity_incint

Specifies a quantify multiple the product must be sold in.

related_product_idsarray of child_scalar

Array of related product IDs.

saleboolean

Indicates whether the product is on sale. If true, the sale_price will be used by default when the product is added to a cart.

sale_pricecurrency

Sale price used to override list price when sale=true.

shipment_dimensionsobjectrequired

Product dimensions when packed for shipping. Typically used by third-party carriers in box packing algorithms to optimize shipping costs.

shipment_locationstring

ID of location from /settings/shipping/locations. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used.

shipment_package_quantityfloat

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.

shipment_pricesarray of object

Product shipping price rules to override default shipping rules.

shipment_weightfloat

If specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg—depending on the store's default weight unit.

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

skustringrequired

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

slugstringrequired

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.

stockarray of Stock

Expandable list of stock adjustments for the product.

stock_backorderboolean

Indicates whether the product can be backordered if out of stock.

stock_levelint

Quantity of the product currently in stock (including all variants), based on the sum of the stock entries.

stock_preorderboolean

Indicates whether the product can be purchased as a preorder.

stock_purchasableboolean

Indicates whether the product's stock is purchasable.

stock_statusenumauto

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.

stock_trackingboolean

Indicates whether the product has stock tracking enabled.

tagsarray of child_scalar

Array of searchable tags to aid in search discoverability.

tax_classstring

Indicates the tax class for the product.

tax_codestring

Product tax code for tracking with Avalara, TaxJar, etc.

typestring

Implies the ordering and fulfillment options available for the product. Can be standard, subscription, bundle, or giftcard. A standard product is a physical item that will be shipped to a customer.

up_sellsarray of object

List of products to display as up-sells on a product detail page.

variableboolean

Indicates whether the product has variant generation enabled.

variantsarray of Variants

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.

virtualboolean

Indicates whether the product is virtual.

The product model
{
  "name": "Iron dagger",
  "sku": "00090616",
  "active": true,
  "purchase_options": {
    "standard": {
      "active": true,
      "price": 10,
      "sale_price": null,
      "sale": false,
      "prices": []
    },
    "subscription": {
      "active": true,
      "plans": [
        {
          "name": "Monthly",
          "description": "1 dagger/month",
          "price": 9,
          "billing_schedule": {
            "interval": "monthly",
            "interval_count": 1,
            "limit": null,
            "trial_days": 14
          },
          "id": "627c6f180d375a001296b593",
          "active": true
        }
      ]
    }
  },
  "variable": true,
  "description": "<h3>Damage: 7</h3><h3>Weight: 8</h3><h3>Health: 98</h3><h3>Speed: 1.4</h3><h3>Reach: 0.6</h3>",
  "tags": [],
  "meta_title": null,
  "meta_description": null,
  "slug": "iron-dagger",
  "attributes": {
    "blade": "",
    "dagger": "",
    "type": [
      "Fine",
      "Rusty"
    ]
  },
  "delivery": "shipment",
  "bundle": null,
  "price": 10,
  "stock_tracking": false,
  "options": [
    {
      "id": "627c6e36e80393798c171670",
      "values": [
        {
          "id": "627c6f18e80393798c171673",
          "name": "Fine",
          "price": null,
          "shipment_weight": null,
          "description": "A better-than-usual iron dagger"
        },
        {
          "id": "627c6f18e80393798c171674",
          "name": "Rusty",
          "price": 0,
          "shipment_weight": null,
          "description": "This dagger's seen better days"
        }
      ],
      "name": "Type",
      "active": true,
      "input_type": "select",
      "variant": true,
      "description": null,
      "required": true,
      "attribute_id": "type"
    }
  ],
  "currency": "USD",
  "sale": false,
  "sale_price": null,
  "prices": [],
  "type": "standard",
  "tax_class": "standard",
  "date_created": "2022-05-12T02:21:12.534Z",
  "stock_status": null,
  "date_updated": "2022-05-12T02:37:45.666Z",
  "category_index": {
    "sort": {
      "627c6db5632818001272f8ed": 0,
      "627c6dc30d375a001296a8b7": 0
    },
    "id": [
      "627c6db5632818001272f8ed",
      "627c6dc30d375a001296a8b7"
    ]
  },
  "cross_sells": [],
  "up_sells": [
    {
      "id": "627c7225e80393798c17167b",
      "product_id": "627c715e632818001274ebd8"
    }
  ],
  "id": "627c6f180d375a001296b580"

Create a new product.

Arguments

namestringrequired

Human-friendly name of the product.

attributesobject

An object containing custom attribute key/value pairs. See attributes for more details.

pricecurrency

List price used when sale=false or sale_price is not defined.

slugstring

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.

POST/products
const swell = require('swell-node').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"
}

Retrieve an existing product using the ID that was returned when created.

Arguments

idobjectIdrequired

The id of the product 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 category 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/products/:id
const swell = require('swell-node').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",
  "date_updated": "2019-04-02T00:26:23.399Z",
  "delivery": "shipment",
  "description": null,
  "images": [
    {
      "id": "5ca24abb9c077817e5fe2b37",
      "file": {
        "id": "5ca24abb9c077817e5fe2b38",
        "date_uploaded": "2019-04-02T00:26:23.399Z",
        "length": 66764,
        "md5": "99194f53bfdea832553e7fa8ae8fd80f",
        "content_type": "image/png",
        "url": "http://cdn.swell.store/test/5ca24abb9c077817e5fe2b36/99194f53bfdea832553e7fa8ae8fd80f",
        "width": 940,
        "height": 600
      }
    }
  ],
  "meta_description": null,
  "meta_title": null,
  "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": 9.99,
  "slug": "swell-t-shirt",
  "stock_level": 0,
  "stock_status": "available",
  "stock_tracking": true,
  "tags": [],
  "type": "standard"
}

Updates 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

idobjectIdrequired

Unique identifier for the product.

activeboolean

Set true to make the product visible to customers in a storefront, otherwise it will be hidden.

attributesobject

An object containing custom attribute key/value pairs. See attributes for more details.

namestring

Human-friendly name of the product.

pricecurrency

List price used when sale=false or sale_price is not defined.

slugstring

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.

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

await swell.put('/products/{id}', {
  id: '5c8fb5e1ed2faf8c79da492a',
  price: 19.98,
  // use $set to override values
  $set: {
    options: [
      ...
    ],
  },
});
Response
{
  "id": "5ca24abb9c077817e5fe2b36",
  "active": true,
  "attributes": {},
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "delivery": "shipment",
  "description": null,
  "images": [
    {
      "id": "5ca24abb9c077817e5fe2b37",
      "file": {
        "id": "5ca24abb9c077817e5fe2b38",
        "date_uploaded": "2019-04-02T00:26:23.399Z",
        "length": 66764,
        "md5": "99194f53bfdea832553e7fa8ae8fd80f",
        "content_type": "image/png",
        "url": "http://cdn.swell.store/test/5ca24abb9c077817e5fe2b36/99194f53bfdea832553e7fa8ae8fd80f",
        "width": 940,
        "height": 600
      }
    }
  ],
  "meta_description": null,
  "meta_title": null,
  "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": 9.99,
  "slug": "swell-t-shirt",
  "stock_level": 0,
  "stock_status": "available",
  "stock_tracking": true,
  "tags": [],
  "type": "standard"
}

Return a list of products.

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
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products', {
  where: { active: true },
  limit: 25,
  page: 1,
});
Response
{
  "count": 51,
  "results": [
    {
      "id": "5ca24abb9c077817e5fe2b36",
      "active": true,
      "attributes": {},
      "currency": "USD",
      "date_created": "2019-04-01T00:00:00.000Z",
      "date_updated": "2019-04-01T00:00:00.000Z",
      "delivery": "shipment",
      "description": null,
      "images": [],
      "meta_description": null,
      "meta_title": null,
      "name": "T-Shirt",
      "options": [],
      "price": 9.99,
      "slug": "swell-t-shirt",
      "stock_level": 0,
      "stock_status": "available",
      "stock_tracking": true,
      "tags": [],
      "type": "standard"
    },
    {...},
    {...}
  ],
  "page": 1,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "2": {
      "start": 51,
      "end": 51
    }
  }
}

Deleting a product that has already been sold will break any links that exist within orders. We recommend only deleting products that have not yet been sold to a customer.

⚠️

When deleting a record that has child collections such as variants and stock, the contents of those collections are also deleted.

Arguments

idobjectIdrequired

The id of the product you wish to delete.

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

await swell.delete('/products/{id}', {
  id: '5c8fb5e1ed2faf8c79da492a',
});
Response
{
  "id": "5ca24abb9c077817e5fe2b36",
  "active": true,
  "attributes": {},
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "delivery": "shipment",
  "description": null,
  "images": [],
  "meta_description": null,
  "meta_title": null,
  "name": "T-Shirt",
  "options": [],
  "price": 9.99,
  "slug": "swell-t-shirt",
  "stock_level": 0,
  "stock_status": "available",
  "stock_tracking": true,
  "tags": [],
  "type": "standard"
}