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

emailstringrequired

Customer's email address.

addressesarray of Addresses

Expandable list of saved addresses on file.

attributesobject

An object containing custom attribute key/value pairs.

balancecurrency

Balance of customer credits.

billingobject

Default customer billing information.

cardsarray of Cards

Expandable list of saved credit cards on file.

cart_abandoned_countint

Number of abandoned carts initiated by the customer.

cartsCart

Expandable list of carts created by the customer.

contactContact

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

contactsContact

Expandable list of all contacts.

contact_idobjectId

The ID of the primary contact.

creditsarray of Credits

Expandable list of customer 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 customer was created.

date_first_cart_abandoneddate

Date the customer first abandoned a shopping cart.

date_first_orderdate

Date the customer placed their first order.

date_last_cart_abandoneddate

Date the customer last abandoned a shopping cart.

date_last_logindate

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

invoicesInvoice

Expandable list of invoices issued for the customer.

last_namestring

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

localestring

Customer’s preferred locale code.

metadataobject

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

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.

notesstring

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

ordersOrder

Expandable list of orders placed by the customer.

order_countint

Number of orders the customer has placed over time.

order_valuecurrency

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.

password_tokenstring

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

phonestring

Customer's phone number.

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

shippingobject

Default customer shipping information.

subscriptionsSubscription

Expandable list of subscriptions held by the customer.

typeenum

Type of customer. 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"
}