Backend API

There are several parameters you can use to effect the outcome of a query.

Query parameter reference for querying with Swell's Backend API.

Fields

where

object

An object containing criteria to filter results by.

sort

string

A string expression used to sort results.

limit

int

A number indicating the max number of results to return up to 1000.

page

int

A number indicating which page of results to return.

search

string

A string to search and filter results by.

expand

string

A string or array of fields to expand in the result.

include

object

An object with additional queries to include as fields in the result.

Use the where parameter to filter results by their values. Swell offers native support for most MongoDB Query Operators including comparison operators like $gt and $lt—logical operators like $and and $or—and many others. You can combine many fields in one query.

Example query using where
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products', {
  where: {
    date_created: { $gte: '2018-01-01T00:00:00Z' },
    stock_level: { $gt: 0 },
    active: true,
  },
});

Use the sort parameter to sort results. The format consists of <field> <direction>. Direction is recognized as a case-insensitive word like ascending and descending, or as abbreviated asc and desc.

You can combine multiple sort fields in a string or array, with the first taking precedence in order.

Example query using sort
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products', {
  sort: 'name asc', // or desc
});

Use the limit parameter to determine how many records should be returned in a result, up to 1000. Defaults to 15. Optionally use in combination with page to perform pagination.

Example query using limit
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products', {
  limit: 100,
});

Use the page parameter to determine which page of results to return, relative to the default or specified limit. Defaults to 1.

Example query using page
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products', {
  page: 2,
});

Use the search parameter to perform a text search across all text fields in a given collection. This is a basic implementation that uses a combination of regular expressions, meaning it will match exact words only. For example, a search for "blue shirts" will match records containing both the words "blue" and "shirts". Searching is not case-sensitive.

When building product search for a complex store, we recommend Algolia.

Example query using search
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products', {
  search: 'blue shirts',
});

Expanding allows you to include related records as defined by link or collection fields. For example, in the cart model, items are linked to a product with the product field which means they aren't automatically included in the result when retrieving a cart. Since the item product is nested in a list of objects, you would use dot-notation to specify the path to the expandable field.

When the expandable field refers to many records, you may want to specify a limit to include more than the default limit, which is 5. To do that for example, use the format variants:50 with the field name and limit separated by :.

When retrieving a list of results, expand will be performed on all records in the result set.

Example query using expand
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/carts/{id}', {
  id: '5407e0929fe97f9d4c712a5e',
  expand: [
    'items.product',
    'items.variant',
  ],
});
Response
{
  "id": "5407e0929fe97f9d4c712a5e",
  "items": [
    {
      "id": "5407e0929fe97f9d4c712a5f",
      "product_id": "5407e0929fe97f9d4c712a5g",
      "product": {
        "name": "Example product",
        ...
      }
    },
    {...}
  ],
  ...
}

Use the include parameter to include results in a query that may or may not be related to the records being retrieved. For example, when you know there's a need to retrieve two similar records at a time in order to reduce the number of API calls a page would need.

Use include.params to specify relative values to the records returned by the main query. The actual field values will be substituted by the API. Use include.data to specify literal values for filtering the included result.

Example query using `include`
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/orders/{id}', {
  id: '5407e0929fe97f9d4c712a5f',
  include: {
    fulfilled_giftcards: {
      url: '/giftcards',
      params: {
        order_id: 'id',
      },
      data: {
        balance: { $gt: 0 },
      },
    },
  },
});
Response
{
  "id": "5407e0929fe97f9d4c712a5f",
  "fulfilled_giftcards": [
    {
      "id": "5407e0929fe97f9d4c712a5g",
      "balance": 25
    },
    {...}
  ],
  ...
}