# Products

Source: https://developers.swell.is/frontend-api/products

**Swell.js:**

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

### List products

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

**List products**

**swell.js**

```javascript
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**

**swell.js**

```javascript
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**

**swell.js**

```javascript
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**

**swell.js** `By slug`

```javascript
await swell.products.get('blue-shoes')
```

**swell.js** `By ID`

```javascript
await swell.products.get('5c15505200c7d14d851e510f')
```

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

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

**Get a product variation**

**swell.js**

```javascript
const variation = 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**

**swell.js**

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

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

**Adding search fields to the product model**

`PUT /:models/products`

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.put('/:models/products/searches/default', {
  fields: ['name', 'slug', 'sku'],
});
```

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

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](https://developers.swell.is/frontend-api/basic-usage) in Basic usage.

#### List filtering

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

**List filters**

**swell.js**

```- Select a language -
const products = await swell.products.list({ limit: 100 })

const filters = swell.products.filters(products)
```

> **Tip:** 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**

**swell.js**

```json
[
  {
    "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"
      }
    ]
  }
]
```

#### 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**

**swell.js**

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

**GraphQL:**

### 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`.

**List products**

**GraphQL**

```graphql
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`.

**List products with variants**

**GraphQL**

```graphql
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`.

**Get products with prices**

**GraphQL**

```graphql
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`.

**List products by category**

**GraphQL**

```graphql
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`.

**Get a product**

**GraphQL** `By slug`

```graphql
query getProductBySlug {
  productBySlug(slug: "blue-shoes", _currency: "USD") {
    id
    name
    slug
    price
    currency
  }
}
```

**GraphQL** `By ID`

```graphql
query getProductById {
  productById(id: "5c15505200c7d14d851e510f", _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`.

**Search for products**

**GraphQL**

```graphql
query searchProducts {
  products(search: "black jeans", limit: 25, page: 1) {
    results {
      id
      name
      currency
      slug
      price
    }
  }
}
```