Frontend API

Authenticate customers, fetch and manage their account data.

Use to authenticate a customer with their email address and password. If the email/password combo is correct, their account will be added to the session, making customer-specific methods available. This will set account_logged_in=true and guest=false.

Log in
await swell.account.login('julia@example.com', 'thepassword')

Use to disconnect the account from the current session. This will set account_logged_in=false and guest=true.

Log out
await swell.account.logout()

Use to get information about the customer currently logged in.

Returns the account object, or null if the customer is not logged in.

Get logged in account
await swell.account.get()

Use to create a new customer account and attach it to the current session.

Returns the newly created account object.

Create an account
await swell.account.create({
  email: 'julia@example.com',
  first_name: 'Julia', // Optional
  last_name: 'Sanchez', // Optional
  email_optin: true, // Optional
  password: 'thepassword' // Optional
})

Use to update properties of the account that is currently logged in.

Returns the updated account object if successful. Otherwise, returns a validation error.

Update the account
await swell.account.update({
  email: 'julia@anotherexample.com',
  first_name: 'Julia', // Optional
  last_name: 'Sanchez', // Optional
  email_optin: true, // Optional
  password: 'thepassword' // Optional
})

Use the metadata object to store arbitrary values on an account. As opposed to storing custom fields with the Backend API, the metadata object is publicly accessible, making it easy to add custom data throughout your customer flow. Note: the metadata object can also be queried and updated using the Backend API.

Returns the updated account object.

Update the account metadata
await swell.account.update({
  metadata: {
    any: 'value',
    even: {
      nested: true
    }
  }
})

When updating nested arrays in metadata, you may notice the default behavior is to merge instead of replacing values. To replace array values, use the $set operator to override the entire value.

Replace array values for account updates
await swell.account.update({
  $set: {
    metadata: {
      my_array: [ ... ]
    }
  }
})

Use the recover method to send an email to the customer with a link to reset their password. If the email address provided doesn't exist in the system, no email will be sent.

Returns a value indicating success.

Send a password reset email
await swell.account.recover({
  email: 'julia@example.com'
})

To customize the password reset URL sent to the customer in an email, pass the optional parameter reset_url, including a placeholder for the password reset key: {reset_key}. Swell will automatically generate and substitute the password reset key in the URL before sending an email.

Customize reset password URL
await swell.account.recover({
  email: 'julia@example.com',
  reset_url: 'https://example.com/password-reset?key={reset_key}'
})
💡

Password reset requests automatically expire after 24 hours.

Use to set the customer's new password. This requires the reset_key from the recovery email (see above). The password recovery email should link to your storefront with reset_key as a URL parameter that you can pass to this method.

Reset an account password
await swell.account.recover({
  password: 'thenewpassword',
  reset_key: 'e42e66fc7e3f00e9e179w20ad1841146'
})

Use to get a list of addresses on file for the account. These are stored automatically when a non-guest user checks out and chooses to save their information for later.

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

List addresses
await swell.account.listAddresses()

Use to add a new address to the account.

Returns the newly created address object.

Create an address
await swell.account.createAddress({
  name: 'Julia Sanchez',
  address1: 'Apartment 16B',
  address2: '2602 Pinewood Drive',
  city: 'Jacksonville',
  state: 'FL',
  zip: '32216',
  country: 'US', // Two letter ISO country code
  phone: '904-504-4760'
})

Use to remove an existing address from the account by ID.

Returns the deleted address object.

Delete an address
await swell.account.deleteAddress('5c15505200c7d14d851e510f')

Use to get a list of credit cards on file for the account. These are stored automatically when a non-guest user checks out and chooses to save their information for later.

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

List saved credit cards
await swell.account.listCards()

Use to save a tokenized credit card to the account for future use. Credit card tokens can be created using swell.card.createToken or Stripe.js.

Create a new credit card
await swell.account.createCard({
  token: '...'
})

Use to remove a saved credit card from the account by ID.

Delete a credit card
await swell.account.deleteCard('5c15505200c7d14d851e510f')

Return a list of orders placed by a customer.

List account orders
await swell.account.listOrders({
  limit: 10,
  page: 2
})

Return a single account order by ID.

Get an account order
await swell.account.getOrder('5fab561fb4a4d83c776f45bd')

Return a list of orders placed by a customer including shipments with tracking information.

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

List account orders with shipments
await swell.account.listOrders({
  expand: 'shipments'
})