Backend API

Products

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.

The product model

Fields

id

objectId

Unique identifier for the product.

name

stringrequired

Human-friendly name of the product.

active

boolean

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

purchase_options

object

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.

attributes

object

An object containing custom attribute key/value pairs.

bundle

boolean

Indicates whether the product is a bundle of other products.

bundle_items

array of object

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

category

Category

Expandable link to the primary category.

category_id

objectId

Primary category, commonly used as a navigation anchor.

categories

Category

Expandable link to all related product categories.

category_index

object

Index of categories used for fast lookup operations.

code

string

Unique code to identify the gift card product.

cost

currency

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

cross_sells

array of object

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

currency

string

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

customizable

boolean

Indicates whether the product has custom options enabled.

date_created

dateauto

Date and time the product was created.

date_updated

dateauto

Date and time the product was last updated.

delivery

enumauto

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:

shipmentsubscriptiongiftcard

description

string

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

discontinued

boolean

Indicates whether the product has been discontinued.

images

array of object

List of images depicting the bundle.

meta_title

string

Page title used to override product name in storefronts.

meta_keywords

string

Page keywords used for search engine optimization purposes.

meta_description

string

Page description used for search engine optimization purposes.

options

array 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_price

currency

Reflects the non-sale price of the product

price

currency

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.

prices

array of price

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

quantity_min

int

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

quantity_inc

int

Specifies a quantify multiple the product must be sold in.

related_product_ids

array of child_scalar

Array of related product IDs.

sale

boolean

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_price

currency

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

shipment_dimensions

objectrequired

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

shipment_location

string

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_quantity

float

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_prices

array of object

Product shipping price rules to override default shipping rules.

shipment_weight

float

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

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

sku

stringrequired

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

slug

stringrequired

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.

stock

array of Stock

Expandable list of stock adjustments for the product.

stock_backorder

boolean

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

stock_level

int

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

stock_preorder

boolean

Indicates whether the product can be purchased as a preorder.

stock_purchasable

boolean

Indicates whether the product's stock is purchasable.

stock_status

enumauto

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:

discontinuedpreorderbackorderout_of_stockin_stock

stock_tracking

boolean

Indicates whether the product has stock tracking enabled.

summary

string

A brief product summary.

tags

array of child_scalar

Array of searchable tags to aid in search discoverability.

tax_class

string

Indicates the tax class for the product.

tax_code

string

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

type

string

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_sells

array of object

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

variable

boolean

Indicates whether the product has variant generation enabled.

variants

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

virtual

boolean

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 product

Create a new product. If you wish to generate your own unique ID for the record, it must use BSON ObjectID format for compatibility.

Arguments

name

stringrequired

Human-friendly name of the product.

price

currency

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.

attributes

object

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

slug

string

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 a product

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

Arguments

id

objectIdrequired

The id of the product 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 category 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/products/:id
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products/{id}', {
});
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"
}

Update a product

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

id

objectIdrequired

Unique identifier for the product.

active

boolean

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

attributes

object

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

name

string

Human-friendly name of the product.

price

currency

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.

slug

string

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

List all products

Return a list of products.

Arguments

categories

objectId

Supports filtering a single by a single top-level category with id, or also supports an array of categories and their sub-categories. For an array, notate category IDs within brackets: categories: [ ...ids ].

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

Delete a product

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

id

objectIdrequired

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"
}
← Back: PagesNext: Variants →
© 2024 Swell
Terms of servicePrivacy policy