The Customer resource stores information about a shop'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.

In a shop's checkout settings, there are three options for customer accounts:

  • Accounts are disabled: Customers can't create accounts and can check out only as guests.
  • Accounts are optional: Customers have the choice of either signing into their account or checking out as a guest. Customers can create accounts for themselves, and the shop owner can create an account for a customer and then invite them by email to use it.
  • Accounts are required: Customers can't check out unless they're logged in, and the shop owner must create their accounts.


Authenticated access scopes: com.read_customers, com.write_customers

Customer properties

accepts_marketing

"accepts_marketing": false

Whether the customer has consented to receive marketing material via email.

addresses

"addresses": [

    {

        "address1""HCM",

        "address2"null,

        "city""",

        "company"null,

        "country""Vietnam",

        "first_name""Phan",

        "id"1079541307,

        "last_name""Hải",

        "phone""0555555555",

        "province""Hồ Chí Minh",

        "zip""70000",

        "name""Hải Phan",

        "province_code""HC",

        "country_code""vn",

        "default"true,

        "district""Quận 1",

        "district_code""HC466",

        "ward"null,

        "ward_code"null

    }

]

A list of the ten most recently updated addresses for the customer. Each address has the following properties:

  • address1: The customer's mailing address.
  • address2: An additional field for the customer's mailing address.
  • city: The customer's city, town, or village.
  • 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.
  • customer_id: A unique identifier for the customer.
  • default: Whether this address is the default address for the customer.
  • first_name: The customer's first name.
  • id: A unique identifier for the address.
  • last_name: The customer's last name.
  • name: The customer's first and last names.
  • phone: The customer's phone number at this address.
  • province: The customer's region name. Typically a province, a state, or a prefecture.
  • province_code: The two-letter province code for the customer's region.
  • zip: The customer's postal code, also known as zip, postcode, Eircode, etc.

created_at

"created_at": "2021-05-13T07:29:20.1Z"

The date and time (ISO 8601 format) when the customer was created.

default_address

"addresses": [

    {

        "address1""HCM",

        "address2"null,

        "city""",

        "company"null,

        "country""Vietnam",

        "first_name""Phan",

        "id"1079541307,

        "last_name""Hải",

        "phone""0555555555",

        "province""Hồ Chí Minh",

        "zip""70000",

        "name""Hải Phan",

        "province_code""HC",

        "country_code""vn",

        "default"true,

        "district""Quận 1",

        "district_code""HC466",

        "ward"null,

        "ward_code"null

    }

]

The default address for the customer. The default address has the following properties:

  • address1: The customer's mailing address.
  • address2: An additional field for the customer's mailing address.
  • city: The customer's city, town, or village.
  • 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.
  • customer_id: A unique identifier for the customer.
  • default: Whether this address is the default address for the customer.
  • first_name: The customer's first name.
  • id: A unique identifier for the address.
  • last_name: The customer's last name.
  • name: The customer's first and last names.
  • phone: The customer's phone number at this address.
  • province: The customer's region name. Typically a province, a state, or a prefecture.
  • province_code: The two-letter province code for the customer's region.
  • zip: The customer's postal code, also known as zip, postcode, Eircode, etc.

email

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

The unique email address of the customer. Attempting to assign the same email address to multiple customers returns an error.

first_name

"first_name": "John"

The customer's first name.

id

"id": 1042784950

A unique identifier for the customer.

last_name

"last_name": "Norman"

The customer's last name.

last_order_id

"last_order_id": 234132602919

The ID of the customer's last order.

last_order_name

"last_order_name": "#2111"

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

published

"published": true

States whether the custom collection is visible. Valid values are "true" for visible and "false" for hidden.

multipass_identifier

"multipass_identifier":false

A unique identifier for the customer that's used with ' 'Multipass login.

note

"note": "VIP"

A note about the customer.

orders_count

"orders_count": 4

The number of orders associated with this customer.

phone

"phone": "0333333333"

The unique phone number for this customer. Attempting to assign the same phone number to multiple customers returns an error. The property can be set using different formats, but each format must represent a number that can be dialed from anywhere in the world.

state

"title": "disabled"

The state of the customer's account with a shop. The state can be changed in the Haravan admin or by the customer, but not through the API. Default value: disabled. Valid values:

  • disabled: The customer doesn't have an active account. Customer accounts can be disabled from the Haravan admin at any time.
  • invited: The customer has received an emailed invite to create an account.
  • enabled: The customer has created an account.
  • declined: The customer declined the email invite to create an account.

orders_count

"orders_count": 4

The number of orders associated with this customer.

phone

"phone": "0333333333"

The unique phone number for this customer. Attempting to assign the same phone number to multiple customers returns an error. The property can be set using different formats, but each format must represent a number that can be dialed from anywhere in the world.

tags

"tags": "loyal"

Tags that the shop owner has attached to the customer, formatted as a string of comma-separated values.

total_spent

"total_spent": 0.0000

The total amount of money that the customer has spent across their order history.

total_spent

"total_spent": 0.0000

The total amount of money that the customer has spent across their order history.

updated_at

"updated_at": "2021-05-13T07:29:20.1Z"

The date and time (ISO 8601 format) when the customer was updated.

verified_email

"verified_email":true

Whether the customer has verified their email address.

birthday

"birthday": "2021-05-13T07:29:20.1Z"

The date and time (ISO 8601 format) when the customer was born. Default value: null when empty info

gender

"gender": null

Gender of the customer. Default value: null. Valid values:

  • null: Empty info.
  • 1: The customer is male.
  • 0: The customer is female.

last_order_date

"last_order_date": "2021-05-13T07:29:20.1Z"

The last time the customer made a purchase (ISO 8601 format). Default value: null.

Endpoints

GET https://apis.haravan.com/com/customers.json

Retrieves a list of customers.

ids

Restrict results to customers specified by a comma-separated list of IDs.

since_id

Restrict results to after the specified ID.

created_at_min

Show customers created after a specified date. (format: 2014-04-25T16:15:47-04:00).

created_at_max

Show customers created before a specified date. (format: 2014-04-25T16:15:47-04:00).

updated_at_min

Show customers last updated after a specified date. (format: 2014-04-25T16:15:47-04:00).

updated_at_max

Show customers last updated before a specified date. (format: 2014-04-25T16:15:47-04:00).

limit

Limit of the result.

page

Page to show the result.

fields

Comma-separated list of fields to include in the response.

Retrieve all custom collections by page number. By default, the number of resources on the page is 50.

GET https://apis.haravan.com/com/customers.json?page=1&limit=1

View response

HTTP/1.1 200 OK

{ "customers": [ { "accepts_marketing": false, "addresses": [ { "address1": "182 Lê Đại Hành", "address2": null, "city": null, "company": null, "country": "Vietnam", "first_name": "Haravan Demo", "id": 1058135354, "last_name": null, "phone": null, "province": "Hồ Chí Minh", "zip": "70000", "name": " Haravan Demo", "province_code": "HC", "country_code": "vn", "default": true, "district": "Quận 11", "district_code": "HC476", "ward": "Phường 15", "ward_code": "27208" } ], "created_at": "2020-10-22T03:37:03.796Z", "default_address": { "address1": "182 Lê Đại Hành", "address2": null, "city": null, "company": null, "country": "Vietnam", "first_name": "Haravan Demo", "id": 1058135354, "last_name": null, "phone": null, "province": "Hồ Chí Minh", "zip": "70000", "name": " Haravan Demo", "province_code": "HC", "country_code": "vn", "default": true, "district": "Quận 11", "district_code": "HC476", "ward": "Phường 15", "ward_code": "27208" }, "email": "hello@haravan.com", "phone": null, "first_name": "Haravan Demo", "id": 1037889951, "multipass_identifier": null, "last_name": null, "last_order_id": 1146065300, "last_order_name": "#100027", "note": null, "orders_count": 28, "state": "Disabled", "tags": null, "total_spent": 261380000.0000, "total_paid": 0.0, "updated_at": "2020-10-22T03:37:09Z", "verified_email": false, "group_name": null, "birthday": null, "gender": null, "last_order_date": "2020-10-23T07:37:04Z" } ] }

Retrieve all customer changes after a certain date.

GET https://apis.haravan.com/com/customers.json?updated_at_max=2020-10-23

View response

HTTP/1.1 200 OK

{ "customers": [ { "accepts_marketing": false, "addresses": [ { "address1": "182 Lê Đại Hành", "address2": null, "city": null, "company": null, "country": "Vietnam", "first_name": "Haravan Demo", "id": 1058135354, "last_name": null, "phone": null, "province": "Hồ Chí Minh", "zip": "70000", "name": " Haravan Demo", "province_code": "HC", "country_code": "vn", "default": true, "district": "Quận 11", "district_code": "HC476", "ward": "Phường 15", "ward_code": "27208" } ], "created_at": "2020-10-22T03:37:03.796Z", "default_address": { "address1": "182 Lê Đại Hành", "address2": null, "city": null, "company": null, "country": "Vietnam", "first_name": "Haravan Demo", "id": 1058135354, "last_name": null, "phone": null, "province": "Hồ Chí Minh", "zip": "70000", "name": " Haravan Demo", "province_code": "HC", "country_code": "vn", "default": true, "district": "Quận 11", "district_code": "HC476", "ward": "Phường 15", "ward_code": "27208" }, "email": "hello@haravan.com", "phone": null, "first_name": "Haravan Demo", "id": 1037889951, "multipass_identifier": null, "last_name": null, "last_order_id": 1146065300, "last_order_name": "#100027", "note": null, "orders_count": 28, "state": "Disabled", "tags": null, "total_spent": 261380000.0000, "total_paid": 0.0, "updated_at": "2020-10-22T03:37:09Z", "verified_email": false, "group_name": null, "birthday": null, "gender": null, "last_order_date": "2020-10-23T07:37:04Z" } ] }
GET https://apis.haravan.com/com/customers/count.json

Retrieves a count of all customers.

Count all customers for your shop.

GET https://apis.haravan.com/com/customers/count.json

View response

HTTP/1.1 200 OK

{ "count": 20 }

Retrieves detail a customer with id.

GET https://apis.haravan.com/com/customers/1037889951.json

View response

HTTP/1.1 200 OK

{ "customer": { "accepts_marketing": false, "addresses": [ { "address1": "182 Lê Đại Hành", "address2": null, "city": null, "company": null, "country": "Vietnam", "first_name": "Haravan Demo", "id": 1058135354, "last_name": null, "phone": null, "province": "Hồ Chí Minh", "zip": "70000", "name": " Haravan Demo", "province_code": "HC", "country_code": "vn", "default": true, "district": "Quận 11", "district_code": "HC476", "ward": "Phường 15", "ward_code": "27208" } ], "created_at": "2020-10-22T03:37:03.796Z", "default_address": { "address1": "182 Lê Đại Hành", "address2": null, "city": null, "company": null, "country": "Vietnam", "first_name": "Haravan Demo", "id": 1058135354, "last_name": null, "phone": null, "province": "Hồ Chí Minh", "zip": "70000", "name": " Haravan Demo", "province_code": "HC", "country_code": "vn", "default": true, "district": "Quận 11", "district_code": "HC476", "ward": "Phường 15", "ward_code": "27208" }, "email": "hello@haravan.com", "phone": null, "first_name": "Haravan Demo", "id": 1037889951, "multipass_identifier": null, "last_name": null, "last_order_id": 1146065300, "last_order_name": "#100027", "note": null, "orders_count": 28, "state": "Disabled", "tags": null, "total_spent": 261380000.0000, "total_paid": 0.0, "updated_at": "2020-10-22T03:37:09Z", "verified_email": false, "group_name": null, "birthday": null, "gender": null, "last_order_date": "2020-10-23T07:37:04Z" } }

Create a customer.

POST https://apis.haravan.com/com/customers.json

{
    "customer": {
        "first_name": "Steve",
        "last_name": "Lastnameson",
        "email": "steve.lastnameson@example.com",
        "phone": "05142546011",
        "verified_email": true
    }
}
          

View response

HTTP/1.1 201 Created

{ "customer": { "accepts_marketing": false, "addresses": [], "created_at": "2021-08-18T05:58:03.3618601Z", "default_address": null, "email": "steve.lastnameson@example.com", "phone": "05142546011", "first_name": "Steve", "id": 1050763804, "multipass_identifier": null, "last_name": "Lastnameson", "last_order_id": null, "last_order_name": null, "note": null, "orders_count": 0, "state": "Enabled", "tags": null, "total_spent": 0.0, "total_paid": 0.0, "updated_at": "2021-08-18T05:58:03.3618709Z", "verified_email": false, "group_name": null, "birthday": null, "gender": null, "last_order_date": null } }

Create a customer with send_email_invite.

POST https://apis.haravan.com/com/customers.json

{
    "customer": {
        "first_name": "Steve",
        "last_name": "Lastnameson",
        "email": "steve.lastnameson@example.com",
        "phone": "05142546011",
        "verified_email": true,
        "send_email_invite": true
    }
}
          

View response

HTTP/1.1 201 Created

{ "customer": { "accepts_marketing": false, "addresses": [], "created_at": "2021-08-18T05:58:03.3618601Z", "default_address": null, "email": "steve.lastnameson@example.com", "phone": "05142546011", "first_name": "Steve", "id": 1050763804, "multipass_identifier": null, "last_name": "Lastnameson", "last_order_id": null, "last_order_name": null, "note": null, "orders_count": 0, "state": "Enabled", "tags": null, "total_spent": 0.0, "total_paid": 0.0, "updated_at": "2021-08-18T05:58:03.3618709Z", "verified_email": false, "group_name": null, "birthday": null, "gender": null, "last_order_date": null } }

Create a customer with password and password_confirmation and skip sending the welcome email.

POST https://apis.haravan.com/com/customers.json

{
    "customer": {
        "first_name": "Steve",
        "last_name": "Lastnameson",
        "email": "steve.lastnameson@example.com",
        "phone": "05142546011",
        "verified_email": true,
        "password": "newpass",
        "password_confirmation": "newpass",
        "send_email_welcome": false
    }
}
          

View response

HTTP/1.1 201 Created

{ "customer": { "accepts_marketing": false, "addresses": [], "created_at": "2021-08-18T05:58:03.3618601Z", "default_address": null, "email": "steve.lastnameson@example.com", "phone": "05142546011", "first_name": "Steve", "id": 1050763804, "multipass_identifier": null, "last_name": "Lastnameson", "last_order_id": null, "last_order_name": null, "note": null, "orders_count": 0, "state": "Enabled", "tags": null, "total_spent": 0.0, "total_paid": 0.0, "updated_at": "2021-08-18T05:58:03.3618709Z", "verified_email": false, "group_name": null, "birthday": null, "gender": null, "last_order_date": null } }

Create a customer with the address.

POST https://apis.haravan.com/com/customers.json

{
    "customer": {
        "first_name": "New",
        "last_name": "Haravan",
        "email": "new.haravan@example.com",
        "phone": "04142546011",
        "verified_email": true,
        "password": "newpass",
        "password_confirmation": "newpass",
        "send_email_welcome": false,
        "addresses":[
            {
                    "country": "Vietnam",
                    "first_name": "New",
                    "last_name": "Haravan",
                    "zip": "70000",
                    "address1":"182 Lê Đại Hành",
                    "country_code": "vn",
                    "province_code": "HC",
                    "district_code": "HC476",
                    "ward_code": "27208"
                }
        ]
    }
}
          

View response

HTTP/1.1 201 Created

{ "customer": { "accepts_marketing": false, "addresses": [ { "address1": "182 Lê Đại Hành", "address2": null, "city": null, "company": null, "country": "Vietnam", "first_name": "New", "id": 1084464836, "last_name": "Haravan", "phone": null, "province": "Hồ Chí Minh", "zip": "70000", "name": "Haravan New", "province_code": "HC", "country_code": "vn", "default": true, "district": "Quận 11", "district_code": "HC476", "ward": "Phường 15", "ward_code": "27208" } ], "created_at": "2021-08-18T06:18:27.4880706Z", "default_address": { "address1": "182 Lê Đại Hành", "address2": null, "city": null, "company": null, "country": "Vietnam", "first_name": "New", "id": 1084464836, "last_name": "Haravan", "phone": null, "province": "Hồ Chí Minh", "zip": "70000", "name": "Haravan New", "province_code": "HC", "country_code": "vn", "default": true, "district": "Quận 11", "district_code": "HC476", "ward": "Phường 15", "ward_code": "27208" }, "email": "new.haravan@example.com", "phone": "04142546011", "first_name": "New", "id": 1050764416, "multipass_identifier": null, "last_name": "Haravan", "last_order_id": null, "last_order_name": null, "note": null, "orders_count": 0, "state": "Enabled", "tags": null, "total_spent": 0.0, "total_paid": 0.0, "updated_at": "2021-08-18T06:18:27.4880823Z", "verified_email": false, "group_name": null, "birthday": null, "gender": null, "last_order_date": null } }

Update details for a customer.

PUT https://apis.haravan.com/com/customers/1050764416.json

{
    "customer": {
       "tags": "VIP",
        "email": "change.haravan@example.com",
        "note": "Customer is a great guy"
    }
}
          

View response

HTTP/1.1 200 Ok

{ "customer": { "accepts_marketing": false, "addresses": [ { "address1": "182 Lê Đại Hành", "address2": null, "city": null, "company": null, "country": "Vietnam", "first_name": "New", "id": 1084464836, "last_name": "Haravan", "phone": null, "province": "Hồ Chí Minh", "zip": "70000", "name": "Haravan New", "province_code": "HC", "country_code": "vn", "default": true, "district": "Quận 11", "district_code": "HC476", "ward": "Phường 15", "ward_code": "27208" } ], "created_at": "2021-08-18T06:18:27.488Z", "default_address": { "address1": "182 Lê Đại Hành", "address2": null, "city": null, "company": null, "country": "Vietnam", "first_name": "New", "id": 1084464836, "last_name": "Haravan", "phone": null, "province": "Hồ Chí Minh", "zip": "70000", "name": "Haravan New", "province_code": "HC", "country_code": "vn", "default": true, "district": "Quận 11", "district_code": "HC476", "ward": "Phường 15", "ward_code": "27208" }, "email": "change.haravan@example.com", "phone": "04142546011", "first_name": "New", "id": 1050764416, "multipass_identifier": null, "last_name": "Haravan", "last_order_id": null, "last_order_name": null, "note": "Customer is a great guy", "orders_count": 0, "state": "Enabled", "tags": "VIP", "total_spent": 0.0000, "total_paid": 0.0, "updated_at": "2021-08-18T06:23:19.553646Z", "verified_email": false, "group_name": null, "birthday": null, "gender": null, "last_order_date": null } }

Delete a customer.

Delete https://apis.haravan.com/com/customers/1050764416.json

{}

View response

HTTP/1.1 200 OK

[]

Add customer tags.

POST https://apis.haravan.com/com/customers/1050764416/tags.json

{
    "tags": "a1,a2"
}

View response

HTTP/1.1 200 OK

{ "tags": "VIP,a1,a2" }

Delete customer tags.

DELETE https://apis.haravan.com/com/customers/1050764416/tags.json

{
    "tags": "a1,a2"
}

View response

HTTP/1.1 200 OK

{ "tags": "VIP" }
GET https://apis.haravan.com/com/customers/groups.json

Retrieves a list of all customer groups.

Retrieves a list of all customer groups.

GET https://apis.haravan.com/com/customers/groups.json

View response

HTTP/1.1 200 OK

{ "customer_groups": [ { "id": 39550382, "name": "Tất cả khách hàng", "created_at": "2020-09-18T04:10:29.954Z", "updated_at": "2020-09-18T04:10:29.954Z" }, { "id": 39550398, "name": "Nhận email quảng cáo", "created_at": "2020-09-18T04:10:30.217Z", "updated_at": "2020-09-18T04:10:30.217Z" }, { "id": 39550400, "name": "Khách hàng thân thiết", "created_at": "2020-09-18T04:10:30.259Z", "updated_at": "2020-09-18T04:10:30.259Z" }, { "id": 39550402, "name": "Khách hàng tiềm năng", "created_at": "2020-09-18T04:10:30.298Z", "updated_at": "2020-09-18T04:10:30.298Z" }, { "id": 39550404, "name": "Trong nước", "created_at": "2020-09-18T04:10:30.341Z", "updated_at": "2020-09-18T04:10:30.341Z" }, { "id": 47243142, "name": "test", "created_at": "2021-08-18T04:22:18.793Z", "updated_at": "2021-08-18T04:22:18.793Z" } ] }