Backend API

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.

Fields

idobjectId

Unique identifier for the account.

emailstringrequired

Customer's email address.

addressesarray of

Expandable list of saved addresses on file.

balancecurrency

Balance of account credits.

billingobject

Default customer billing information.

cardsarray of

Expandable list of saved credit cards on file.

cart_abandoned_countintauto

Number of abandoned carts initiated by the customer.

cartscarts

Expandable list of carts created by the customer.

creditsarray of

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

currencystring

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

date_createddateauto

Date and time the account was created.

date_first_cart_abandoneddateauto

Date the customer first abandoned a shopping cart.

date_first_orderdateauto

Date the customer placed their first order.

date_last_cart_abandoneddateauto

Date the customer last abandoned a shopping cart.

date_last_logindateauto

Date the customer last logged into their account.

date_last_orderdate

Date of the last order placed by the customer.

date_updateddateauto

Date and time the account was last updated.

email_optinboolean

Indicates the customer opted into email communications.

first_namestring

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

groupstring

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

invoicesinvoices

Expandable list of invoices issued for the customer.

last_namestringauto

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

namestringrequired

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.

ordersorders

Expandable list of orders placed by the customer.

order_countintauto

Number of orders the customer has placed over time.

order_valuecurrencyauto

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

passwordstring

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

password_reset_keystring

Unique key created when a customer requests a password reset.

password_reset_urlstring

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

phonestring

Customer's phone number.

shippingobject

Default customer shipping information.

subscriptionssubscriptions

Expandable list of subscriptions held by the customer.

typeenum

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

vat_numberstring

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 a new customer account.

Arguments

emailstringrequired

Customer's email address.

namestring

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 existing account using the ID that was returned when created.

Arguments

idobjectIdrequired

ID of the customer account to retrieve.

expandstring

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.

fieldsstring

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.

includestring

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 existing account using the ID that was returned when created.

Arguments

idobjectIdrequired

Unique identifier for the account.

emailstring

Customer's email address.

email_optinboolean

Indicates the customer opted into email communications.

namestring

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.

shippingobject

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"
}

Return a list of customer accounts.

Arguments

expandstring

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.

fieldsstring

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

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

See including for more details.

limitint

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

pageint

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

searchstring

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.

sortstring

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.

whereobject

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

idobjectIdrequired

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"
}