Frontend API
Methods to fetch, search, and manage your store’s products.
Returns all products, with offset pagination using limit and page.
await swell.products.list({
limit: 25, // Max. 100
page: 1
})
Returns all products and their active variants, with offset pagination using limit and page.
await swell.products.list({
limit: 25, // Max. 100
page: 1,
expand: ['variants']
})
Returns products in a specific category, with offset pagination using limit and page.
await swell.products.list({
category: 't-shirts', // Slug or ID
limit: 25, // Max. 100
page: 1
})
Returns a single product.
await swell.products.get('blue-shoes')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.
An optional third argument selects which purchase option to price against. Pass 'standard' or 'subscription', or an object such as { type: 'subscription', plan: 'monthly' } to price a specific subscription plan. Passing a plan without a type implies 'subscription', and if no plan is given, the first plan on the subscription option is used. This method throws when the requested purchase option or plan isn't active on the product.
Returns a new object with product and option/variant values merged together.
const variation = swell.products.variation(product, {
Size: 'Medium',
Color: 'Turquoise'
})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.
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.
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');
await swell.put('/:models/products/searches/default', {
fields: ['name', 'slug', 'sku'],
});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.
These methods build a set of faceted filters from a list of products. To filter a product query by field values instead, pass a where object with query operators such as $or or $gt. See Query operators in Basic usage.
Returns an array of filters given a list of products as input.
const products = await swell.products.list({ limit: 100 })
const filters = 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.
[
{
"id": "price",
"label": "Price",
"type": "range",
"interval": 10,
"options": [
{
"value": 10,
"label": 10
},
{
"value": 100,
"label": 100
}
]
},
{
"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"
}
]
}
]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.
await swell.products.list({
page,
limit,
sort,
categories, // optional category slug or ID
$filters: {
price: [10, 20],
category: ['featured'],
size: ['small', 'large']
}
})
List products
Returns all products, with offset pagination using limit , page, and where.
The parameters for this query are search, where, sort, limit, page, _locale, _currency, and _pricing.
query getAllProducts {
products(limit: 25, page: 1, where: { stock_level: 0 }) {
results {
id
name
slug
price
currency
options {
id
attributeId
name
inputType
active
required
variant
values {
id
name
price
description
}
}
purchaseOptions {
standard {
price
sale
salePrice
}
subscription {
plans {
id
name
price
billingSchedule {
interval
intervalCount
}
}
}
}
}
}
}List products with variants
Returns all products and their active variants, with offset pagination using limit and page.
query getProductsVariants {
products(limit: 25, page: 1) {
results {
id
name
slug
variants {
results {
name
sku
prices {
price
discountPercent
}
purchaseOptions {
standard {
price
sale
salePrice
prices {
price
discountPercent
}
}
}
stockLevel
currency
}
}
}
}
}List products with prices
Returns all products and their prices, with offset pagination using limit and currency.
query getProductsPricesInCurrency {
products(limit: 20, _currency: "USD") {
results {
id
name
slug
origPrice # Static field--shows price without the discount.
salePrice # Static field--shows price with the discount.
price # Dynamic field--price depends if the sale is active. If the sale is active, then price=salePrice. Otherwise price=origPrice when the sale is inactive.
currency
}
}
}
List products by category
Return a list of products within a category, organized by currency.
The parameters for this query are slug, _locale, and _currency.
query getProductsInCurrency {
categoryBySlug(slug: "mens-shirt") {
usd: products(_currency: "USD") {
id
name
price
currency
}
eur: products(_currency: "EUR") {
id
name
price
currency
}
}
}Get a product
Returns a single product and its price by slug or id.
Parameters
- For querying getProductBySlug: slug (required), _locale, _currency, and _pricing.
- For querying getProductById: id (required), _locale, _currency, and _pricing.
query getProductBySlug {
productBySlug(slug: "blue-shoes", _currency: "USD") {
id
name
slug
price
currency
}
}Search for products
Perform a full-text search with a string. Supported search fields: name, slug, and sku. Returns all products matching the search query string, with offset pagination using limit and page.
The parameters for this query are search, where, sort, limit, page, _locale, _currency, and _pricing.
query searchProducts {
products(search: "black jeans", limit: 25, page: 1) {
results {
id
name
currency
slug
price
}
}
}