Backend API

Accounts

Accounts represent a customer's current information and their interactions with your store. Default billing and shipping information are stored, as well as saved credit cards and addresses. Several fields including order_count and order_value give you insight into a customer's buying behavior.

The account model

Fields

id

objectId

Unique identifier for the customer.

email

stringrequired

Customer's email address.

addresses

array of Addresses

Expandable list of saved addresses on file.

attributes

object

An object containing custom attribute key/value pairs.

balance

currency

Balance of customer credits.

billing

object

Default customer billing information.

cards

array of Cards

Expandable list of saved credit cards on file.

cart_abandoned_count

int

Number of abandoned carts initiated by the customer.

carts

Cart

Expandable list of carts created by the customer.

contact

Contact

Expandable list of saved information for the primary contact on file for the account.

contacts

Contact

Expandable list of all contacts.

contact_id

objectId

The ID of the primary contact.

credits

array of Credits

Expandable list of customer credit transactions. Balance of these transactions is kept in balance.

currency

string

Three-letter ISO currency code in uppercase. Defaults to the store's base currency.

date_created

dateauto

Date and time the customer was created.

date_first_cart_abandoned

date

Date the customer first abandoned a shopping cart.

date_first_order

date

Date the customer placed their first order.

date_last_cart_abandoned

date

Date the customer last abandoned a shopping cart.

date_last_login

date

Date the customer last logged into their account.

date_last_order

date

Date of the last order placed by the customer.

date_updated

dateauto

Date and time the customer was last updated.

email_optin

boolean

Indicates the customer opted into email communications.

first_name

string

Customer's first name. If name is updated, then first_name will be automatically updated as the first word of the name.

group

string

Customer group used for special price rules and other customer logic.

invoices

Invoice

Expandable list of invoices issued for the customer.

last_name

string

If name is updated, then last_name will be automatically updated as the last words of the name.

locale

string

Customer’s preferred locale code.

metadata

object

Arbitrary data, typically set in a checkout flow to store custom values. See Frontend API for more details.

name

string

Full name of the customer. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.

notes

string

Internal admin notes. These are not visible to the customer.

orders

Order

Expandable list of orders placed by the customer.

order_count

int

Number of orders the customer has placed over time.

order_value

currency

Total value of all orders the customer has placed over time.

password

string

Password used to log in and gain access to sensitive information. When the customer has a password, they are required to log in when placing an order using the associated email address. This value is automatically encrypted using bcrypt.

If an account does not have a password defined, it is treated as a guest during checkout.

password_reset_key

string

Unique key created when a customer requests a password reset.

password_reset_url

string

When a customer requests password reset, an email is sent with this URL to redirect and authenticate the request.

password_token

string

A temp token generated by Swell, or a permanent password token assigned after submitting a temporary token (starting with password_).

phone

string

Customer's phone number.

segments

array of child_scalar

An array of strings, each representing a segment that the account belongs to. Segments are used to allow groups of customers access to particular coupons or promos.

shipping

object

Default customer shipping information.

subscriptions

Subscription

Expandable list of subscriptions held by the customer.

type

enum

Type of customer. Can be one of individual or business.

Possible enum values:

individualbusiness

vat_number

string

Default VAT number for a business customer, if applicable.

The account model
{
  "id": "60f1994f9111e70000000001",
  "email": "lachance@darkbrotherhood.com",
  "balance": 50,
  "billing": {
    "name": "Lucien Lachance",
    "first_name": "Lucien",
    "last_name": "Lechance",
    "address1": "Abandoned House",
    "city": "Cheydinhal",
    "state": "NY",
    "zip": 11201,
    "country": "US",
    "phone": "(555) 555-5555",
    "method": "card",
    "card": {
      "token": "card_1Ds1K7E30PFlZWil6Q7bJ1PD",
      "test": true,
      "last4": "4242",
      "brand": "Visa",
      "address_check": "unchecked",
      "zip_check": "unchecked",
      "cvc_check": "unchecked",
      "exp_month": 1,
      "exp_year": 2029,
      "fingerprint": "3e63991847bbdaafdbc5c8f110ad803f"
    },
    "account_card_id": "5c3ac9870b3b171a7dfaf089"
  },
  "cart_abandoned_count": 18,
  "currency": "USD",
  "date_created": "2021-07-16T14:35:59.938Z",
  "date_first_cart_abandoned": "2018-01-01T00:00:00.000Z",
  "date_first_order": "2019-01-01T00:00:00.000Z",
  "date_last_cart_abandoned": "2021-07-16T14:35:59.938Z",
  "date_last_login": "2021-07-16T14:35:59.938Z",
  "date_last_order": "2021-07-16T14:35:59.938Z",
  "date_updated": "2021-07-16T14:35:59.938Z",
  "first_name": "Lucien",
  "group": "vip",
  "last_name": "Lechance",
  "name": "Lucien Lechance",
  "order_value": 5,
  "password": "$2a$06$hnxbq8likRXJFRa6VrKn7uayucRZw1dH5EQsHwPbWliy3FoNYIpIq",
  "password_reset_key": null,
  "password_reset_url": null,
  "phone": "(555) 555-5555",
  "shipping": {
    "name": "Lucien Lachance",
    "first_name": "Lucien",
    "last_name": "Lechance",
    "address1": "Abandoned House",
    "city": "Cheydinhal",
    "state": "NY",
    "zip": 11201,
    "country": "US",
    "phone": "(555) 555-5555",
    "account_address_id": "5c12c5fdfcd74b34e19cf659"
  },
  "type": "individual"
}

Create an account

Create a new customer account. If you wish to generate your own unique ID for the record, it must use BSON ObjectID format for compatibility.

Arguments

email

stringrequired

Customer's email address.

name

string

Full name of the customer. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.

POST/accounts
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.post('/accounts', {
  email: 'adoringfan@azurasstar.com',
  first_name: 'Adoring'
  last_name: 'Fan'
  notes: 'Yes, oh great and mighty Grand Champion? Is there something you need? Can I carry your weapon? Shine your boots? Backrub, perhaps?'
});
Response
{
  "name": "Adoring Fan",
  "email": "adoringfan@azurasstar.com",
  "notes": "these are some notes",
  "currency": "USD",
  "date_created": "2022-06-02T19:37:45.237Z",
  "type": "individual",
  "order_count": 0,
  "order_value": 0,
  "balance": 0,
  "date_updated": "2022-06-02T19:38:56.209Z",
  "first_name": "Adoring",
  "last_name": "Fan",
  "notes": "\"Yes, oh great and mighty Grand Champion? Is there something you need? Can I carry your weapon? Shine your boots? Backrub, perhaps?\"
  "id": "629911891d24f70012114a68"
 }

Retrieve an account

Retrieve an existing account using the ID that was returned when created.

Arguments

id

objectIdrequired

ID of the customer account to retrieve.

expand

string

Expanding link fields and child collections is performed using the expand argument.

  • For example, expand=account would return a related customer account if one exists.

When the field represents a collection, you can specify the query limit,

  • For example, expand=variants:10 would return up to 10 records of the variants collection.

See expanding for more details.

fields

string

Return only the specified fields in the result. For example fields=name,slug would return only the fields name and slug in the response. Supports nested object and array fields using dot-notation, for example items.product_id. The customer account id is always returned.

include

string

Include one or more arbitrary queries in the response, possibly related to the main query.

See including for more details.

GET/accounts/:id
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/accounts/{id}', {
});
Response
{
  "type": "individual"
  "email": "customer@example.com",
  "balance": 50,
  "billing": {
    "name": "Martin Septim",
    "first_name": "Martin",
    "last_name": "Septim",
    "address1": "Waynon Priory",
    "city": "Chorrol",
    "state": "NY",
    "zip": 11201,
    "country": "US",
    "phone": "(555) 555-5555",
    "method": "card",
    "card": {
      "token": "card_1Ds1K7E30PFlZWil6Q7bJ1PD",
      "test": true,
      "last4": "4242",
      "brand": "Visa",
      "address_check": "unchecked",
      "zip_check": "unchecked",
      "cvc_check": "unchecked",
      "exp_month": 1,
      "exp_year": 2029,
      "fingerprint": "3e63991847bbdaafdbc5c8f110ad803f"
    },
    "account_card_id": "5c3ac9870b3b171a7dfaf089"
  },
  "cart_abandoned_count": 18,
  "currency": "USD",
  "date_created": "2021-07-16T14:35:59.938Z",
  "date_first_cart_abandoned": "2018-01-01T00:00:00.000Z",
  "date_first_order": "2019-01-01T00:00:00.000Z",
  "date_last_cart_abandoned": "2021-07-16T14:35:59.938Z",
  "date_last_login": "2021-07-16T14:35:59.938Z",
  "date_last_order": "2021-07-16T14:35:59.938Z",
  "date_updated": "2021-07-16T14:35:59.938Z",
  "first_name": "Martin",
  "group": "Dragonborn",
  "last_name": "Septim",
  "name": "Martin Septim",
  "order_value": 5,
  "password": "$2a$06$hnxbq8likRXJFRa6VrKn7uayucRZw1dH5EQsHwPbWliy3FoNYIpIq",
  "password_reset_key": null,
  "password_reset_url": null,
  "phone": "(555) 555-5555",
  "shipping": {
    "name": "Martin Septim",
    "first_name": "Martin",
    "last_name": "Septim",
    "address1": "Waynon Priory",
    "city": "Chorrol",
    "state": "NY",
    "zip": 11201,
    "country": "US",
    "phone": "(555) 555-5555",
    "account_address_id": "5c12c5fdfcd74b34e19cf659"
  },
  "notes": "\"Voiced by Sean Bean.\"",
  "id": "60f1994f9111e70000000007",
}

Update an account

Update an existing account using the ID that was returned when created.

Arguments

id

objectIdrequired

Unique identifier for the account.

email

string

Customer's email address.

email_optin

boolean

Indicates the customer opted into email communications.

name

string

Full name of the customer. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.

shipping

object

Default customer shipping information.

PUT/accounts/:id
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.put('/accounts/{id}', {
  email: 'sheogorath@shiveringisles.com'
});
Response
{
  "first_name": "Sheogorath",
  "email": "sheogorath@shiveringisles.com",
  "group": "Deadric princes",
  "currency": "USD",
  "name": "Sheogorath",
  "date_created": "2022-06-02T19:56:55.028Z",
  "type": "individual",
  "order_count": 0,
  "order_value": 0,
  "balance": 50000,
  "id": "62991607782f3b0013cf17af"
}

List all accounts

Return a list of customer accounts.

Arguments

expand

string

Expand link fields and child collections by using the expand argument.

  • For example, expand=account would return a related customer account if one exists.

When the field represents a collection, you can specify the query limit.

  • For example, expand=variants:10 would return up to 10 records of the variants collection.

See expanding for more details.

fields

string

Returns only the specified fields in the result.

  • For example fields=name,slug would return only the fields name and slug in the response.

Supports nested object and array fields using dot-notation.

  • For example, items.product_id. The product id is always returned.

include

object

Include one or more arbitrary queries in the response which are potentially related to the main query.

See including for more details.

limit

int

Limit the number of records returned, ranging between 1 and 1000. Defaults to 15.

page

int

The page number of results to return given the specified or default limit.

search

string

A text search is performed using the search argument. Searchable fields are defined by the model.

  • For example, search=red would return records containing the word "red" anywhere in the defined text fields.

See searching for more details.

sort

string

Expression to sort results by using a format similar to a SQL sort statement.

  • For example, sort=name asc would return records sorted by name ascending.

See sorting for more details.

where

object

An object with criteria to filter the result.

  • For example, active=true would return records containing a field active with the value true.

It's also possible to use query operators, for example, $eq, $ne, $gt, and more.

See querying for more details.

GET/accounts
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/accounts', {
  where: {
    order_count: {
      $gt: 1
    }
  },
  limit: 25,
  page: 1
});
Response
{
  "count": 51,
  "results": [
  {
  "type": "individual"
  "email": "customer@example.com",
  "balance": 50,
  "billing": {
    "name": "Martin Septim",
    "first_name": "Martin",
    "last_name": "Septim",
    "address1": "Waynon Priory",
    "city": "Chorrol",
    "state": "NY",
    "zip": 11201,
    "country": "US",
    "phone": "(555) 555-5555",
    "method": "card",
    "card": {
      "token": "card_1Ds1K7E30PFlZWil6Q7bJ1PD",
      "test": true,
      "last4": "4242",
      "brand": "Visa",
      "address_check": "unchecked",
      "zip_check": "unchecked",
      "cvc_check": "unchecked",
      "exp_month": 1,
      "exp_year": 2029,
      "fingerprint": "3e63991847bbdaafdbc5c8f110ad803f"
    },
    "account_card_id": "5c3ac9870b3b171a7dfaf089"
  },
  "cart_abandoned_count": 18,
  "currency": "USD",
  "date_created": "2021-07-16T14:35:59.938Z",
  "date_first_cart_abandoned": "2018-01-01T00:00:00.000Z",
  "date_first_order": "2019-01-01T00:00:00.000Z",
  "date_last_cart_abandoned": "2021-07-16T14:35:59.938Z",
  "date_last_login": "2021-07-16T14:35:59.938Z",
  "date_last_order": "2021-07-16T14:35:59.938Z",
  "date_updated": "2021-07-16T14:35:59.938Z",
  "first_name": "Martin",
  "group": "Dragonborn",
  "last_name": "Septim",
  "name": "Martin Septim",
  "order_value": 5,
  "password": "$2a$06$hnxbq8likRXJFRa6VrKn7uayucRZw1dH5EQsHwPbWliy3FoNYIpIq",
  "password_reset_key": null,
  "password_reset_url": null,
  "phone": "(555) 555-5555",
  "shipping": {
    "name": "Martin Septim",
    "first_name": "Martin",
    "last_name": "Septim",
    "address1": "Waynon Priory",
    "city": "Chorrol",
    "state": "NY",
    "zip": 11201,
    "country": "US",
    "phone": "(555) 555-5555",
    "account_address_id": "5c12c5fdfcd74b34e19cf659"
  },
  "notes": "\"Voiced by Sean Bean.\"",
  "id": "60f1994f9111e70000000007",
  },
    {...},
    {...}
  ],
  "page": 1,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "2": {
      "start": 51,
      "end": 51
    }
  }
}

Delete an account

Delete a customer account permanently by clearing all records (carts, orders, invoices, and subscriptions) from the account. Use $force_delete: true in the same request to do so.

Arguments

id

objectIdrequired

The ID of the account to delete.

DELETE/accounts/:id
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.delete('/accounts/{id}', {
  id: '60f1994f9111e7000000000a'
});
Response
{
  "id": "60f1994f9111e7000000000d",
  "email": "customer@example.com",
  "balance": 50,
  "billing": {
    "name": "Jon Snow",
    "first_name": "Jon",
    "last_name": "Snow",
    "address1": "1 Main Street",
    "city": "Brooklyn",
    "state": "NY",
    "zip": 11201,
    "country": "US",
    "phone": "(555) 555-5555",
    "method": "card",
    "card": {
      "token": "card_1Ds1K7E30PFlZWil6Q7bJ1PD",
      "test": true,
      "last4": "4242",
      "brand": "Visa",
      "address_check": "unchecked",
      "zip_check": "unchecked",
      "cvc_check": "unchecked",
      "exp_month": 1,
      "exp_year": 2029,
      "fingerprint": "3e63991847bbdaafdbc5c8f110ad803f"
    },
    "account_card_id": "5c3ac9870b3b171a7dfaf089"
  },
  "cart_abandoned_count": 18,
  "currency": "USD",
  "date_created": "2021-07-16T14:35:59.938Z",
  "date_first_cart_abandoned": "2018-01-01T00:00:00.000Z",
  "date_first_order": "2019-01-01T00:00:00.000Z",
  "date_last_cart_abandoned": "2021-07-16T14:35:59.938Z",
  "date_last_login": "2021-07-16T14:35:59.938Z",
  "date_last_order": "2021-07-16T14:35:59.938Z",
  "date_updated": "2021-07-16T14:35:59.938Z",
  "first_name": "Jon",
  "group": "vip",
  "last_name": "Snow",
  "name": "Jon Snow",
  "order_value": 5,
  "password": "$2a$06$hnxbq8likRXJFRa6VrKn7uayucRZw1dH5EQsHwPbWliy3FoNYIpIq",
  "password_reset_key": null,
  "password_reset_url": null,
  "phone": "(555) 555-5555",
  "shipping": {
    "name": "Jon Snow",
    "first_name": "Jon",
    "last_name": "Snow",
    "address1": "1 Main Street",
    "city": "Brooklyn",
    "state": "NY",
    "zip": 11201,
    "country": "US",
    "phone": "(555) 555-5555",
    "account_address_id": "5c12c5fdfcd74b34e19cf659"
  },
  "type": "individual"
}
← Back: Subscription plansNext: Account addresses →
© 2025 Swell
Terms of servicePrivacy policy