Filter
What would you like to search for?
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
Unique identifier for the account.
Customer's email address.
Expandable list of saved addresses on file.
Balance of account credits.
Default customer billing information.
ID of the customer's credit card on file, if applicable.
Expandable link to the customer's credit card on file, if applicable.
Billing address line 1: street address/PO box/company name.
Billing address line 2: apartment/suite/unit/building.
Credit card billing details used when billing.method=card.
Token generated by Swell Checkout or Stripe.js.
When used with a payment gateway that performs address checks and address1 was provided. Can be pass, fail, unavailable, or unchecked.
Credit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.
When used with a payment gateway that performs CVC code checks and cvc was provided. Can be pass, fail, unavailable, or unchecked.
Two-digit number representing the credit card expiration month.
Four-digit number representing the credit card expiration year.
ID of the payment gateway that should be used to process payments.
Last four digits of the card number.
Indicates this is a test card.
When used with a payment gateway that performs address checks and zip was provided. Can be pass, fail, unavailable, or unchecked.
Billing city/district/suburb/town/village.
Two-letter ISO country code.
Billing first name. If name is updated, then first_name will be automatically updated as the first word of the name.
Billing last name. If name is updated, then last_name will be automatically updated as the last words of the name.
Method of payment. Can be `card`, `account` or any one of the manual methods defined in payment settings.
Billing full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.
Billing phone number.
Billing state/county/province/region.
VAT number for a business customer associated with this billing method, if applicable.
Billing zip/postal code.
Expandable list of saved credit cards on file.
Number of abandoned carts initiated by the customer.
Expandable list of carts created by the customer.
Expandable list of account credit transactions. Balance of these transactions is kept in balance.
Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
Date and time the account was created.
Date the customer first abandoned a shopping cart.
Date the customer placed their first order.
Date the customer last abandoned a shopping cart.
Date the customer last logged into their account.
Date of the last order placed by the customer.
Date and time the account was last updated.
Indicates the customer opted into email communications.
Customer's first name. If name is updated, then first_name will be automatically updated as the first word of the name.
Customer group used for special price rules and other customer logic.
Expandable list of invoices issued for the customer.
If name is updated, then last_name will be automatically updated as the last words of the name.
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.
Expandable list of orders placed by the customer.
Number of orders the customer has placed over time.
Total value of all orders the customer has placed over time.
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.
Unique key created when a customer requests a password reset.
When a customer requests password reset, an email is sent with this URL to redirect and authenticate the request.
Customer's phone number.
Default customer shipping information.
ID of the customer's address on file.
Expandable link to the customer's address on file.
Shipping address line 1: street address/PO box/company name.
Shipping address line 2: apartment/suite/unit/building.
Shipping city/district/suberb/town/village.
Two-letter ISO country code.
Shipping first name. If name is updated, then first_name will be automatically updated as the first word of the name.
Shipping last name. If name is updated, then last_name will be automatically updated as the last words of the name.
Shipping full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first and last.
Shipping phone number.
Shipping state/county/province/region.
Shipping zip/postal code.
Expandable list of subscriptions held by the customer.
Type of customer account. Can be one of individual or business.
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
Customer's email address.
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.
Default customer billing information.
Setting this value will populate billing.card with the associated customer's credit card on file.
Billing address line 1: street address/PO box/company name.
Billing address line 2: apartment/suite/unit/building.
Credit card billing details used when billing.method=card.
Token generated by Swell Checkout or Stripe.js.
Credit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.
Two-digit number representing the credit card expiration month.
Four-digit number representing the credit card expiration year.
Last four digits of the card number.
Billing city/district/suburb/town/village.
Two-letter ISO country code.
Billing first name. If name is updated, then first_name will be automatically updated as the first word of the name.
Billing last name. If name is updated, then last_name will be automatically updated as the last words of the name.
Billing full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.
Method of payment. Can be card, account, or any one of the manual methods defined in payment settings.
Billing phone number.
Billing state/county/province/region.
VAT number for a business customer associated with this billing method, if applicable.
Billing zip/postal code.
Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
Date of the last order placed by the customer.
Indicates the customer opted into email communications.
Customer's first name. If name is updated, then first_name will be automatically updated as the first word of the name.
Customer group used for special price rules and other customer logic.
If name is updated, then last_name will be automatically updated as the last words of the name.
Password used to login 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.
Unique key created when a customer requests a password reset.
When a customer requests password reset, an email is sent with this URL to redirect and authenticate the request.
Customer's phone number.
Default customer shipping information.
Setting this value will populate shipping with the associated customer's account address on file.
Shipping address line 1: street address/PO box/company name.
Shipping address line 2: apartment/suite/unit/building.
Shipping city/district/suburb/town/village.
Two-letter ISO country code.
Shipping first name. If name is updated, then first_name will be automatically updated as the first word of the name.
Shipping last name. If name is updated, then last_name will be automatically updated as the last words of the name.
Shipping full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.
Shipping phone number.
Shipping state/county/province/region.
Shipping zip/postal code.
Type of customer account. Can be one of individual or business.
Default VAT number for a business customer, if applicable.
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
ID of the customer account to retrieve.
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.
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 one or more arbitrary queries in the response, possibly related to the main query.
See including for more details.
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
Unique identifier for the account.
Customer's email address.
Indicates the customer opted into email communications.
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.
Default customer shipping information.
Setting this value will populate shipping with the associated customer's account address on file.
Shipping address line 1: street address/PO box/company name.
Shipping address line 2: apartment/suite/unit/building.
Shipping city/district/suburb/town/village.
Two-letter ISO country code.
Shipping first name. If name is updated, then first_name will be automatically updated as the first word of the name.
Shipping last name. If name is updated, then last_name will be automatically updated as the last words of the name.
Shipping full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.
Shipping phone number.
Shipping state/county/province/region.
Shipping zip/postal code.
Default customer billing information.
Setting this value will populate billing.card with the associated customer's credit card on file.
Billing address line 1: street address/PO box/company name.
Billing address line 2: apartment/suite/unit/building.
Credit card billing details used when billing.method=card.
Token generated by Swell Checkout or Stripe.js.
Credit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.
Two-digit number representing the credit card expiration month.
Four-digit number representing the credit card expiration year.
Last four digits of the card number.
Billing city/district/suburb/town/village.
Two-letter ISO country code.
Billing first name. If name is updated, then first_name will be automatically updated as the first word of the name.
Billing last name. If name is updated, then last_name will be automatically updated as the last words of the name.
Billing full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.
Method of payment. Can be card, account, or any one of the manual methods defined in payment settings.
Billing phone number.
Billing state/county/province/region.
VAT number for a business customer associated with this billing method, if applicable.
Billing zip/postal code.
Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
Date of the last order placed by the customer.
Customer's first name. If name is updated, then first_name will be automatically updated as the first word of the name.
Customer group used for special price rules and other customer logic.
If name is updated, then last_name will be automatically updated as the last words of the name.
Password used to login 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.
Unique key created when a customer requests a password reset.
When a customer requests password reset, an email is sent with this URL to redirect and authenticate the request.
Customer's phone number.
Type of customer account. Can be one of individual or business.
Default VAT number for a business customer, if applicable.
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
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.
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 one or more arbitrary queries in the response which are potentially related to the main query.
See including for more details.
Limit the number of records returned, ranging between 1 and 1000. Defaults to 15.
The page number of results to return given the specified or default limit.
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.
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.
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.
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
The id of the account to delete.
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"
}