swell-storefront

Storefront API

Client-side applications can use the Swell Storefront API to retrieve public data including products, shopping carts, and account information.

Getting started

npm install swell-storefront --save

Basic example:

import swell from 'swell-storefront';

swell.auth('my-store', 'pk_...');

swell.products.get({
  category: 't-shirts',
  limit: 25,
  page: 1,
}).then((products) => {
  console.log(products);
});

Products

List products

swell.products.get({
  limit: 25,
  page: 1,
});

List products by category

swell.products.get({
  category: 't-shirts',
  limit: 25,
  page: 1,
});

Search products

swell.products.get({
  search: 'blue jeans',
  limit: 25,
  page: 1,
});

Get a product by ID

swell.products.get('5c15505200c7d14d851e510f');

Get a product by slug

swell.products.get('pink-shoes');

Get a product by slug with variants

swell.products.get('pink-shoes', {
  expand: ['variants'],
});

Categories

List categories

swell.categories.get({
  limit: 25,
  page: 1,
});

Get a category by slug

swell.categories.get('mens-shoes');

Get a category by ID

swell.categories.get('5c15505200c7d14d851e510f');

Shopping carts

Get the cart

This request will return null if nothing has been added to the cart yet.

swell.cart.get();

Add an item

This request will return null if nothing has been added to the cart yet.

swell.cart.addItem({
  product_id: '5c15505200c7d14d851e510f',
  quantity: 1,
  options: [{
    id: 'color',
    value: 'Blue',
  }],
});

Update an item

swell.cart.updateItem('5c15505200c7d14d851e510f', {
  quantity: 2,
});

Update all items

swell.cart.updateItems([{
  quantity: 2,
}, {
  quantity: 3,
}, {
  quantity: 4,
}]);

Remove an item

swell.cart.removeItem('5c15505200c7d14d851e510f');

Remove all items

swell.cart.removeItems();

Recover a shopping cart

This is typically used with an abandoned cart recovery email. Your email may have a link to your store with a checkout_id identifying the cart that was abandoned. Making this request will add the cart to the current session and mark it as recovered.

swell.cart.recover('878663b2fb4175b128e40de428cd7b0c');

Customer account

Login

If the email/password is correct, the account will be added to the session and make other related endpoints available to the client.

swell.account.login('[e-mail]', 'password');

Logout

This will remove the account from the current session and shopping cart.

swell.account.logout();

Get logged in account

swell.account.get();

Create a new account

swell.account.create({
  email: '[e-mail]',
  first_name: 'John',
  last_name: 'Doe',
  email_optin: true,
});

Update logged in account

swell.account.update({
  email: '[e-mail]',
  first_name: 'Jane',
  last_name: 'Doe',
  email_optin: false,
});

Send password recovery email

swell.account.recover({
  email: '[e-mail]',
});

Recovery account password

swell.account.recover({
  reset_key: '...',
  password: 'new password',
});

List addresses

swell.account.getAddresses();

Create a new address

swell.account.createAddress({
  name: 'Ship to name',
  address1: '...',
  address2: '...',
  city: '...',
  state: '...',
  zip: '...',
  country: '...',
  phone: '...',
});

Delete an address

swell.account.deleteAddress('5c15505200c7d14d851e510f');

List saved credit cards

swell.account.getCards();

Create a new credit card

Credit card tokens can be created using Schema.js or Stripe.js.

swell.account.createCard({
  token: 't_...',
});

Delete a credit card

swell.account.deleteCard('5c15505200c7d14d851e510f');