Methods to fetch, search, and manage your store’s products.

List products

Returns all products, with offset pagination using limit and page.

List products
await swell.products.list({
  limit: 25, // Max. 100
  page: 1
})

List products with variants

Returns all products and their active variants, with offset pagination using limit and page.

List products with variants
await swell.products.list({
  limit: 25, // Max. 100
  page: 1,
  expand: ['variants']
})

List products by category

Returns products in a specific category, with offset pagination using limit and page.

List products by category
await swell.products.list({
  category: 't-shirts', // Slug or ID
  limit: 25, // Max. 100
  page: 1
})

Get a product

Returns a single product.

Get a product
await swell.products.get('blue-shoes')

Get a product variation

Returns a single product variation matching selected options.

Resolves the variation price, sale_price, orig_price, and stock_status values based on the customer's chosen options. Typically you would retrieve a product (link to retrieve a product) earlier in the page's lifecycle and pass it to this method along with the options. Options can be either an array or an object with option name/value pairs.

Returns a new object with product and option/variant values merged together.

Get a product variation
await swell.products.variation(product, {
  Size: 'Medium',
  Color: 'Turquoise'
})

Search for products

Perform a full-text search with a string. The search operation is performed using AND syntax, where all words must be present in at least one of the supported search fields of the product. Supported search fields: id, name, slug, sku.

Returns products matching the search query string, with offset pagination using limit and page.

Search for products
await swell.products.list({
  search: 'black jeans', // Any text string
  limit: 25, // Max. 100
  page: 1
})

You can expand a model's search query field array to include additional search fields.

Adding search fields to the product model
// As illustrated with swell-node
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.post('/products', {
  id: 'default',
  fields: [
    {
      'name',
      'slug',
      'sku',
      'description',
      'stock',
      'price',
    },
   ],
});

Filtering

Methods to simplify product filtering, typically as part of a search or category page. The type of filters supported include price range, categories, and attributes.

List filtering

Returns an array of filters given a list of products as input.

List filters
const products = await swell.products.list(...)

await swell.products.filters(products)

A filter list is based on the set of input products, therefore your page should retrieve the full set of relevant products before applying filters.

Price and category filters are identified explicitly by price and category IDs, respectively. Other filters are identified by their attribute ID.

Product filters
[
  {
    "id": "price",
    "label": "Price",
    "type": "range",
    "interval": 10,
    "options": [
      {
        "value": 10,
        "label": "$10.00"
      },
      {
        "value": 100,
        "label": "$100.00"
      }
    ]
  },
  {
    "id": "category",
    "label": "Category",
    "type": "select",
    "options": [
      {
        "value": "t-shirts",
        "label": "T-Shirts"
      },
      {
        "value": "featured",
        "label": "Featured products"
      }
    ]
  },
  {
    "id": "size",
    "label": "Size",
    "type": "select",
    "options": [
      {
        "value": "small",
        "label": "Small"
      },
      {
        "value": "medium",
        "label": "Medium"
      },
      {
        "value": "large",
        "label": "Large"
      }
    ]
  }
]

Apply filtering

Pass a $filters object when retrieving products. Each property represents a filter by ID, and an array of values to filter the resulting product list.

Applying filtering
await swell.products.list({
  page,
  limit,
  sort,
  categories, // optional category slug or ID
  $filters: {
    price: [10, 20],
    category: ['featured'],
    size: ['small', 'large']
  }
})