API Customer

The Customer resource stores information about a store's customers, such as their contact details, their order history, and whether they've agreed to receive email marketing.

The Customer resource also holds information on the status of a customer's account. Customers with accounts save time at checkout when they're logged in because they don't need to enter their contact information. You can use the Customer API to check whether a customer has an active account, and then invite them to create one if they don't.

For security reasons, the Customer resource doesn't store credit card information. Customers always need to enter this information when they go to the checkout.

Customer Properties

id	{ "id" : 123456789 } A unique numeric identifier for the customer.
title	{ "title": "Mr" } The salutation or title for the customer.
first_name	{ "first_name": "Bilbo" } The customer's first name.
last_name	{ "last_name": "Baggins" } The customer's last name.
name	{ "name": "Mr Bilbo Baggins" } The customer's full name.
email	{ "email": "bilbo@lordoftherings.com" } The unique email address of the customer. Attempting to assign the same email address to multiple customers returns an error.
default_address	{ "default_address": { "id": 1969, "title": "Mr", "first_name": "Bilbo", "last_name": "Baggins", "name": "Mr Bilbo Baggins", "company": "The Fellowship of the Ring", "address1": "2 Bag End", "address2": "", "city": "Hobbiton", "province": "Waikato", "province_code": "WKO", "country": "New Zealand", "country_code": "NZ", "zip": "1234", "phone": "123456789", "default": true } } The default address for the customer.
addresses	{ "addresses": [ { "id": 1969, "title": "Mr", "first_name": "Bilbo", "last_name": "Baggins", "name": "Mr Bilbo Baggins", "company": "The Fellowship of the Ring", "address1": "2 Bag End", "address2": "", "city": "Hobbiton", "province": "Waikato", "province_code": "WKO", "country": "New Zealand", "country_code": "NZ", "zip": "1234", "phone": "123456789", "default": true } ] } A list of the customer's addresses.
accepts_marketing	{ "accepts_marketing": false } This indicates whether the customer has consented to receive marketing material via email.
note	{ "note": "This customer is eligible for the frequent traveller bonus." } A note about the customer.
orders_count	{ "orders_count": 32 } The number of orders associated with this customer.
state	{ "state": "enabled" } The state of the customer's account with a store. The state can be changed in the toolbox or by the customer, but not through the API. It is disabled by default. Valid values are: guest: The customer does not have an account. disabled: The customer doesn't have an active account. Customer acounts can be disabled from the toolbox at any time. invited: The customer has received an emailed invitation to create an account. enabled: The customer has created an account. declined: The customer declined the email invitation to create an account.
total_spent	{ "total_spent": "465.30" } The total amount of money that the customer has spent across their order history.
sign_in_count	{ "sign_in_count": 314 } The number of times that the customer has signed in.
current_sign_in_at	{ "current_sign_in_at": "2017-09-20T10:47:18.424+10:00" } The time of the current sign-in.
current_sign_in_ip	{ "current_sign_in_ip": "192.168.10.200" } The IP address used by the customer for the current sign-in.
last_sign_in_at	{ "last_sign_in_at": "2017-09-20T10:43:18.716+10:00" } The time of the previous sign-in.
last_sign_in_ip	{ "last_sign_in_ip": "192.168.10.200" } The IP address used by the customer for the previous sign-in.
last_order_id	{ "last_order_id": 23919 } The ID of the customer's last order.
wholesale	{ "wholesale": true } The customer has access to wholesale pricing.
credit	{ "credit": 15.40 } The amount of store credit that the customer has in their account.
accounting_id	{ "accounting_id": "2b74006d-a599-42dd-b228-52596f49333c" } This field is used if the store has a supported accounting app installed. The field is used to store the value of the customer record id in the associated accounting software. This value can then be used to ensure that all orders for this customer are posted to the same customer account in the accounting software.
pos_id	{ "pos_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4" } This field is used if the store has a supported point of sale app installed. The field is used to store the value of the customer record id in the associated point of sale software. This value can then be used to ensure that all orders for this customer are posted to the same customer account in the point of sale software.
tags	{ "tags": "loyal,wholesaler" } Tags that the store owner has attached to the customer, formatted as a string of comma-separated values.
created_at	{ "created_at": "2008-07-15T20:00:00-04:00" } The date and time (ISO 8601 format) when the customer was created.
updated_at	{ "updated_at": "2008-07-16T20:00:00-04:00" } The date and time (ISO 8601 format) when the customer was last updated.

Endpoints

GET /api/customers.json

Retrieve a list of customers.

Optional Parameters

limit	Number of results returned. The default is 30, with a maximum of 50 in a single request.
page	The number of the page to return. The number of results per page is set by the limit parameter. If more results are required, then submit the request again, increasing the page number each time.
ids	Restrict results to customers specified by a comma-separated list of IDs.
since_id	Limit the results to only include objects which have an id greater than the given value.
wholesale_status	Limit the results to only include customers with the given wholesale status ('wholesale' or 'retail').
marketing_status	Limit the results to only include customers with the given marketing status ('accepts_marketing' or 'rejects_marketing').
created_at_min	Return only the customers created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max	Return only the customers created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min	Return only the customers updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max	Return only the customers updated before the given date and time. Use the format "2014-12-31 12:00".
fields	A comma-separated list of fields to return in the response. If a list of fields is provided, then the default_address and addresses fields will always be excluded.

Example Request and Response

GET /api/customers.json

HTTP/1.1 200 OK

{
  "customers": [
    {
      "id": 6,
      "title": "Mr",
      "first_name": "Bilbo",
      "last_name": "Baggins",
      "name": "Mr Bilbo Baggins",
      "email": "bilbo@lordoftherings.com",
      "accepts_marketing": true,
      "note": "Here is some sample text.",
      "orders_count": 200,
      "state": "enabled",
      "total_spent": 13908.63,
      "created_at": "2010-06-15T23:15:50.925+10:00",
      "updated_at": "2017-09-20T10:47:18.428+10:00",
      "sign_in_count": 314,
      "current_sign_in_at": "2017-09-20T10:47:18.424+10:00",
      "current_sign_in_ip": "192.168.10.200",
      "last_sign_in_at": "2017-09-20T10:43:18.716+10:00",
      "last_sign_in_ip": "192.168.10.200",
      "last_order_id": 1353,
      "wholesale": false,
      "credit": 0.0,
      "accounting_id": "2b74006d-a599-42dd-b228-52596f49333c",
      "pos_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
      "tags": "wholesaler",
      "default_address": {
        "id": 1969,
        "title": "Mr",
        "first_name": "Bilbo",
        "last_name": "Baggins",
        "name": "Mr Bilbo Baggins",
        "company": "The Fellowship of the Ring",
        "address1": "2 Bag End",
        "address2": "",
        "city": "Hobbiton",
        "province": "Waikato",
        "province_code": "WKO",
        "country": "New Zealand",
        "country_code": "NZ",
        "zip": "1234",
        "phone": "123456789",
        "default": true
      },
      "addresses": [
        {
          "id": 1969,
          "title": "Mr",
          "first_name": "Bilbo",
          "last_name": "Baggins",
          "name": "Mr Bilbo Baggins",
          "company": "The Fellowship of the Ring",
          "address1": "2 Bag End",
          "address2": "",
          "city": "Hobbiton",
          "province": "Waikato",
          "province_code": "WKO",
          "country": "New Zealand",
          "country_code": "NZ",
          "zip": "1234",
          "phone": "123456789",
          "default": true
        }
      ]
    }, ...
  ]
}

Examples using filters

GET /api/customers.json?fields=id,name,email

GET /api/customers.json?whole_status=wholesale

GET /api/customers.json?ids=232133,354345,234234

GET /api/customers/search.json

Searches for customers that match a supplied query.

Optional Parameters

limit	Number of results returned. The default is 30, with a maximum of 50 in a single request.
page	The number of the page to return. The number of results per page is set by the limit parameter. If more results are required, then submit the request again, increasing the page number each time.
query	Text to search for in the store's customer data. The text is used to search the customer's name, email address and location. Additionally, or instead, search filters can be added to limit the search. A search filter may be prefixed by '-' to indicate the condition is negated. For example, the following search filter could be specified - '-country:Australia total_spent:>100' The following search filters can be specified: accepts_marketing (0 or 1) country (country name) last_abandoned_order_date (last_week or last_month) order_date (last_week, last_month, last_3_months, <yyyy-mm-dd or >yyyy-mm-dd) orders_count (n, <n or >n) state (guest, enabled, disabled, invited, declined) total_spent (n, <n or >n) credit (n, <n or >n) wholesale (0 or 1)
since_id	Limit the results to only include objects which have an id greater than the given value.
wholesale_status	Limit the results to only include customers with the given wholesale status ('wholesale' or 'retail').
marketing_status	Limit the results to only include customers with the given marketing status ('accepts_marketing' or 'rejects_marketing').
created_at_min	Return only the customers created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max	Return only the customers created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min	Return only the customers updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max	Return only the customers updated before the given date and time. Use the format "2014-12-31 12:00".
fields	A comma-separated list of fields to return in the response. If a list of fields is provided, then the default_address and addresses fields will always be excluded.

Example Request and Response

GET /api/customers/search.json?query=Bilbo country:"New Zealand" total_spent:>100

HTTP/1.1 200 OK

GET /api/customers/count.json

Return a count of the number of customers.

Optional Parameters

since_id	Limit the results to only include objects which have an id greater than the given value.
wholesale_status	Limit the results to only include customers with the given wholesale status ('wholesale' or 'retail').
marketing_status	Limit the results to only include customers with the given marketing status ('accepts_marketing' or 'rejects_marketing').
created_at_min	Return only the customers created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max	Return only the customers created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min	Return only the customers updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max	Return only the customers updated before the given date and time. Use the format "2014-12-31 12:00".

Example Request and Response

GET /api/customers/count.json

HTTP/1.1 200 OK

{
  "count": 14567
}

Examples using filters

GET /api/customers/count.json?marketing_status=accepts_marketing

GET /api/customers/CUSTOMER_ID.json

Retrieves a single customer by ID.

Optional Parameters

fields	A comma-separated list of fields to return in the response. If a list of fields is provided, then the default_address and addresses fields will always be excluded.

Example Request and Response

GET /api/customers/6.json

HTTP/1.1 200 OK

{
  "customer": {
    "id": 6,
    "title": "Mr",
    "first_name": "Bilbo",
    "last_name": "Baggins",
    "name": "Mr Bilbo Baggins",
    "email": "bilbo@lordoftherings.com",
    "accepts_marketing": true,
    "note": "Here is some sample text.",
    "orders_count": 200,
    "state": "enabled",
    "total_spent": 13908.63,
    "created_at": "2010-06-15T23:15:50.925+10:00",
    "updated_at": "2017-09-20T10:47:18.428+10:00",
    "sign_in_count": 314,
    "current_sign_in_at": "2017-09-20T10:47:18.424+10:00",
    "current_sign_in_ip": "192.168.10.200",
    "last_sign_in_at": "2017-09-20T10:43:18.716+10:00",
    "last_sign_in_ip": "192.168.10.200",
    "last_order_id": 1353,
    "wholesale": false,
    "credit": 0.0,
    "tags": "wholesaler",
    "default_address": {
      "id": 1969,
      "title": "Mr",
      "first_name": "Bilbo",
      "last_name": "Baggins",
      "name": "Mr Bilbo Baggins",
      "company": "The Fellowship of the Ring",
      "address1": "2 Bag End",
      "address2": "",
      "city": "Hobbiton",
      "province": "Waikato",
      "province_code": "WKO",
      "country": "New Zealand",
      "country_code": "NZ",
      "zip": "1234",
      "phone": "123456789",
      "default": true
    },
    "addresses": [
      {
        "id": 1969,
        "title": "Mr",
        "first_name": "Bilbo",
        "last_name": "Baggins",
        "name": "Mr Bilbo Baggins",
        "company": "The Fellowship of the Ring",
        "address1": "2 Bag End",
        "address2": "",
        "city": "Hobbiton",
        "province": "Waikato",
        "province_code": "WKO",
        "country": "New Zealand",
        "country_code": "NZ",
        "zip": "1234",
        "phone": "123456789",
        "default": true
      }
    ]
  }
}

POST /api/customers.json

Creates a customer.

Example Request and Response

POST /api/customers.json

{
  "customer": {
    "title": "Mr",
    "first_name": "Gandalf",
    "last_name": "Wizard",
    "email": "gandalf@lordoftherings.com",
    ...
  }
}

HTTP/1.1 201 Created

PUT /api/customers/CUSTOMER_ID.json

Updates a customer.

Example Request and Response

PUT /api/customers/6.json

{
  "customer": {
    "id": 6,
    "note": "The ring has been found."
  }
}

HTTP/1.1 200 OK

DELETE /api/customers/CUSTOMER_ID.json

Deletes a customer.

Example Request and Response

DELETE /api/customers/6.json

HTTP/1.1 200 OK

{}

Further Reference

• An Introduction to the Spiffy Stores API
• Creating Private API Keys
• Using the API
• API Reference