Customer

A customer resource instance represents a customer account with the shop. Customer accounts store contact information for the customer, saving logged-in customers the trouble of having to provide it at every checkout. For security reasons, the customer resoruce instance does not store credit card information. Customers will always have to provide this information at checkout.

#

The customer resource instance also stores some additional information about the customer for the benefit of the shop owner, including: the number of orders, the amount of money s/he has spent and number of orders s/he has made throughout his/her history with the shop as well as the shop owner's notes and tags for the customer.

The shop's use of customer accounts will depend on its Customer Checkout settings. For shop owners, this is located in the shop admin dashboard in the "Preferences" tab, on the "Checkout and Payment" page. There are three options for this setting:

  • Guest checkout only: Customer accounts are disabled. meaning that customers can't log in and can only check out as guests.
  • Guest checkout with optional sign-in: Customer accounts are optional. Customers have the choice of either signing into their account or simply checking out as a guest. Under this setting, customers can create accounts for themselves; the shop owner can also an account for a customer and then invite him/her by email to use it.
  • Sign-in required: Customer accounts are required. Customers can't check out unless logged in, and under this setting, the shop owner must create accounts for them first.

What can you do with Customer?

The haravan API lets you do the following with the Customer resource. More detailed versions of these general actions may be available:

Customer Properties

accepts_marketing
{ "accepts_marketing" : false }

Indicates whether the customer has consented to be sent marketing material via email. Valid values are "true" and "false."

addresses
{ "address1" : "Chestnut Street 92" }
{ "address2" : "Apartment 2" }
{ "city" : "Louisville" }
{ "company" : "null" }
{ "country" : "united states" }
{ "first_name" : "Bob" }
{ "id" : 207119551 }
{ "last_name" : "Norman" }
{ "phone" : "555-625-1199" }
{ "province" : "Kentucky" }
{ "zip" : "40202" }
{ "province_code" : "KY" }
{ "country_code" : "US" }
{ "country_name" : "United States" }
{ "default" : "null" }


A list of addresses for the customer. Each address may have the following properties:

  • address1: The customer's mailing address.
  • address2: An additional field for the customer's mailing address.
  • city: The customer's city.
  • company: The customer's company.
  • country: The customer's country.
  • country_code: The two-letter country code corresponding to the customer's country.
  • country_name: The customer's normalized country name.
  • default: Indicates whether this address is the default address for the customer. Valid values are "true" and "false."
  • first_name: The customer's first name.
  • id: A unique numeric identifier for the address.
  • last_name: The customer's last name.
  • name: The customer's name.
  • phone: The customer's phone number.
  • province: The customer's province or state name.
  • province_code: The two-letter pcode for the customer's province or state.
  • zip: The customer's zip or postal code.


created_at
{ "created_at" : "2013-06-27T08:48:27-04:00" }

The date and time when the customer was created. The API returns this value in ISO 8601 format.

default_address
{ "address1" : "Chestnut Street 92" }
{ "address2" : "Apartment 2" }
{ "city" : "Louisville" }
{ "company" : "null" }
{ "country" : "united states" }
{ "first_name" : "Bob" }
{ "id" : 207119551 }
{ "last_name" : "Norman" }
{ "phone" : "555-625-1199" }
{ "province" : "Kentucky" }
{ "zip" : "40202" }
{ "province_code" : "KY" }
{ "country_code" : "US" }
{ "country_name" : "United States" }
{ "default" : "null" }


The default address for the customer. The default address may have the following properties:

  • address1: The customer's mailing address.
  • address2: An additional field for the customer's mailing address.
  • city: The customer's city.
  • company: The customer's company.
  • country: The customer's country.
  • country_code: The two-letter country code corresponding to the customer's country.
  • country_name: The customer's normalized country name.
  • default: Indicates whether this address is the default address for the customer. Valid values are "true" and "false."
  • first_name: The customer's first name.
  • id: A unique numeric identifier for the address.
  • last_name: The customer's last name.
  • name: The customer's name.
  • phone: The customer's phone number.
  • province: The customer's province or state name.
  • province_code: The two-letter pcode for the customer's province or state.
  • zip: The customer's zip or postal code.


email
{ "email" : "bob.norman@hostmail.com" }

The email address of the customer.

first_name
{ "first_name" : "John" }

The customer's first name.

id
{ "id" : 207119551 }

A unique numeric identifier for the customer.

metafield
{ "key" : "new" }
{ "value" : "newvalue" }
{ "value_type" : "string" }
{ "key" : "global" }


Attaches additional metadata to a shop's resources:

  • key (required):Identifier for the metafield (maximum of 30 characters).
  • namespace (required): Container for a set of metadata. Namespaces help distinguish between metadata you created and metadata created by another individual with a similar namespace (maximum of 20 characters).
  • value (required): Information to be stored as metadata.
  • value_type (required): States whether the information in the value is stored as a 'string' or 'integer.'
  • description (optional): Additional information about the metafield.


multipass_identifier
{ "multipass_identifier" : "null" }

The customer's identifier used with Multipass login

last_name
{ "last_name" : "Norman" }

The customer's last name.

last_order_id
{ "last_order_id" : "null" }

The id of the customer's last order.

last_order_name
{ "last_order_name" : "null" }

The name of the customer's last order. This is directly related to the Order's name field.

note
{ "note" : "null" }

A note about the customer.

orders_count
{ "orders_count" : 0 }

The number of orders associated with this customer.

state
{ "state" : "null" }


The state of the customer in a shop. Customers start out as "disabled." They are invited by email to setup an account with a shop. The customer can then:

  • decline: decline the invite to start an account that saves their customer settings.
  • invited: accept the invite to start an account that saves their customer settings. Customers then change from "disabled to "enabled."

Shop owners also have the ability to disable a customer. This will cancel a customer's membership with a shop.


tags
{ "tags" : "tagsational" }

Tags are additional short descriptors formatted as a string of comma-separated values. For example, if an article has three tags: tag1, tag2, tag3.

total_spent
{ "total_spent" : 0.0 }

The total amount of money that the customer has spent at the shop.

updated_at
{ "updated_at" : "2012-08-24T14:01:46-04:00" }

The date and time when the customer information was updated. The API returns this value in ISO 8601 format.

verified_email
{ "verified_email" : "true" }

States whether or not the email address has been verified.

Endpoints

GET/admin/customers.json

Retrieve all customers of a shop

since_id

Restrict results to after the specified ID

created_at_min

Show customers created after date (format: 2008-12-31 03:00)

created_at_max

Show customers created before date (format: 2008-12-31 03:00)

updated_at_min

Show customers last updated after date (format: 2008-12-31 03:00)

updated_at_max

Show customers last updated before date (format: 2008-12-31 03:00)

limit

Amount of results

(default: 50) (maximum: 250)
page

Page to show

(default: 1)
fields

comma-separated list of fields to include in the response

Get all customers for a shop

GET /admin/customers.json
View Response
HTTP/1.1 200 OK
{
  "customers": [
    {
      "accepts_marketing": false,
      "created_at": "2015-03-28T13:28:28-04:00",
      "email": "bob.norman@hostmail.com",
      "first_name": "Bob",
      "id": 207119551,
      "last_name": "Norman",
      "last_order_id": 450789469,
      "multipass_identifier": null,
      "note": null,
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "41.94",
      "updated_at": "2015-03-28T13:28:28-04:00",
      "verified_email": true,
      "tags": "",
      "last_order_name": "#1001",
      "default_address": {
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "company": null,
        "country": "United States",
        "first_name": null,
        "id": 207119551,
        "last_name": null,
        "phone": "555-625-1199",
        "province": "Kentucky",
        "zip": "40202",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
      },
      "addresses": [
        {
          "address1": "Chestnut Street 92",
          "address2": "",
          "city": "Louisville",
          "company": null,
          "country": "United States",
          "first_name": null,
          "id": 207119551,
          "last_name": null,
          "phone": "555-625-1199",
          "province": "Kentucky",
          "zip": "40202",
          "name": "",
          "province_code": "KY",
          "country_code": "US",
          "country_name": "United States",
          "default": true
        }
      ]
    }
  ]
}

Get all customers for a shop after a specified ID

GET /admin/customers.json?since_id=207119551
View Response
HTTP/1.1 200 OK
{
  "customers": [
    {
      "accepts_marketing": false,
      "created_at": "2015-03-28T13:28:34-04:00",
      "email": "steve.lastnameson@example.com",
      "first_name": "Steve",
      "id": 1018520252,
      "last_name": "Lastnameson",
      "last_order_id": null,
      "multipass_identifier": null,
      "note": null,
      "orders_count": 0,
      "state": "disabled",
      "total_spent": "0.00",
      "updated_at": "2015-03-28T13:28:34-04:00",
      "verified_email": true,
      "tags": "",
      "last_order_name": null,
      "default_address": {
        "address1": "123 Oak St",
        "address2": null,
        "city": "Ottawa",
        "company": null,
        "country": "Canada",
        "first_name": "Mother",
        "id": 1053317301,
        "last_name": "Lastnameson",
        "phone": "555-1212",
        "province": "Ontario",
        "zip": "123 ABC",
        "name": "Mother Lastnameson",
        "province_code": "ON",
        "country_code": "CA",
        "country_name": "Canada",
        "default": true
      },
      "addresses": [
        {
          "address1": "123 Oak St",
          "address2": null,
          "city": "Ottawa",
          "company": null,
          "country": "Canada",
          "first_name": "Mother",
          "id": 1053317301,
          "last_name": "Lastnameson",
          "phone": "555-1212",
          "province": "Ontario",
          "zip": "123 ABC",
          "name": "Mother Lastnameson",
          "province_code": "ON",
          "country_code": "CA",
          "country_name": "Canada",
          "default": true
        }
      ]
    }
  ]
}

Get all customers for a shop changed after a certain date

GET /admin/customers.json?updated_at_min=2015-03-27 17:28:36
View Response
HTTP/1.1 200 OK
{
  "customers": [
    {
      "accepts_marketing": false,
      "created_at": "2015-03-28T13:28:34-04:00",
      "email": "bob.norman@hostmail.com",
      "first_name": "Bob",
      "id": 207119551,
      "last_name": "Norman",
      "last_order_id": 450789469,
      "multipass_identifier": null,
      "note": null,
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "41.94",
      "updated_at": "2015-03-28T13:28:34-04:00",
      "verified_email": true,
      "tags": "",
      "last_order_name": "#1001",
      "default_address": {
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "company": null,
        "country": "United States",
        "first_name": null,
        "id": 207119551,
        "last_name": null,
        "phone": "555-625-1199",
        "province": "Kentucky",
        "zip": "40202",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
      },
      "addresses": [
        {
          "address1": "Chestnut Street 92",
          "address2": "",
          "city": "Louisville",
          "company": null,
          "country": "United States",
          "first_name": null,
          "id": 207119551,
          "last_name": null,
          "phone": "555-625-1199",
          "province": "Kentucky",
          "zip": "40202",
          "name": "",
          "province_code": "KY",
          "country_code": "US",
          "country_name": "United States",
          "default": true
        }
      ]
    }
  ]
}

Haravan - Công ty công nghệ cung cấp giải pháp kinh doanh thương mại điện tử, duy nhất tại Việt Nam được Google lựa chọn vào chương trình bệ phóng tiềm năng với hỗ trợ và đào tạo công nghệ để vươn ra thị trường quốc tế vững chắc.