Customer

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.

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

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.

What you can 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

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

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


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": "2013-06-27T08:48:27-04:00"

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

default_address
"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": true
}


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

  • address1: The first line of 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: Returns true for each default address.
  • 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 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": 207119551

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": "#1169"

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

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


Attaches additional metadata to a shop's resources:

  • key (required): An identifier for the metafield (maximum of 30 characters).
  • namespace(required): A container for a set of metadata (maximum of 20 characters). Namespaces help distinguish between metadata that you created and metadata created by another individual with a similar namespace.
  • value (required): Information to be stored as metadata.
  • value_type (required): The value type. Valid values: string and integer.
  • description (optional): Additional information about the metafield.
multipass_identifier
"multipass_identifier": null

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

note
"note": "Placed an order that had a fraud warning"

A note about the customer.

orders_count
"orders_count": 3

The number of orders associated with this customer.

phone
"phone": "+16135551111"


The unique phone number (E.164 format) 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. The following formats are all valid:

  • 6135551212
  • +16135551212
  • (613)555-1212
  • +1 613-555-1212
state
"state": "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 acounts 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.
tags
"tags": "loyal"

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

tax_exempt
"tax_exempt": true

Whether the customer is exempt from paying taxes on their order. If true, then taxes won't be applied to an order at checkout. If false, then taxes will be applied at checkout.

total_spent
"total_spent": "375.30"

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

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

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

verified_email
"verified_email": true

Whether the customer has verified their email address.

Endpoints

GET/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 those 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

The maximum number of results to show.

(default: 50, maximum: 250)
page

The page of results to show.

(default: 1)
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve all customers for a shop

GET /com/customers.json
Hide response
HTTP/1.1 200 OK
{
"customers": [
{
    "id": 207119551,
    "email": "bob.norman@hostmail.com",
    "accepts_marketing": false,
    "created_at": "2018-07-11T14:37:16-04:00",
    "updated_at": "2018-07-11T14:37:16-04:00",
    "first_name": "Bob",
    "last_name": "Norman",
    "orders_count": 1,
    "state": "disabled",
    "total_spent": "41.94",
    "last_order_id": 450789469,
    "note": null,
    "verified_email": true,
    "multipass_identifier": null,
    "tax_exempt": false,
    "phone": null,
    "tags": "",
    "last_order_name": "#1001",
    "addresses": [
    {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
    }
    ],
    "admin_graphql_api_id": "gid://haravan/Customer/207119551",
    "default_address": {
    "id": 207119551,
    "customer_id": 207119551,
    "first_name": null,
    "last_name": null,
    "company": null,
    "address1": "Chestnut Street 92",
    "address2": "",
    "city": "Louisville",
    "province": "Kentucky",
    "country": "United States",
    "zip": "40202",
    "phone": "555-625-1199",
    "name": "",
    "province_code": "KY",
    "country_code": "US",
    "country_name": "United States",
    "default": true
    }
}
]
}

Retrieve all customers after a specified ID

GET /com/customers.json?since_id=207119551
Hide response
HTTP/1.1 200 OK
{
"customers": [
{
    "id": 1073339457,
    "email": "steve.lastnameson@example.com",
    "accepts_marketing": false,
    "created_at": "2018-07-11T14:38:11-04:00",
    "updated_at": "2018-07-11T14:38:11-04:00",
    "first_name": "Steve",
    "last_name": "Lastnameson",
    "orders_count": 0,
    "state": "disabled",
    "total_spent": "0.00",
    "last_order_id": null,
    "note": null,
    "verified_email": true,
    "multipass_identifier": null,
    "tax_exempt": false,
    "phone": "+15142546011",
    "tags": "",
    "last_order_name": null,
    "addresses": [
    {
        "id": 1053317287,
        "customer_id": 1073339457,
        "first_name": "Mother",
        "last_name": "Lastnameson",
        "company": null,
        "address1": "123 Oak St",
        "address2": null,
        "city": "Ottawa",
        "province": "Ontario",
        "country": "Canada",
        "zip": "123 ABC",
        "phone": "555-1212",
        "name": "Mother Lastnameson",
        "province_code": "ON",
        "country_code": "CA",
        "country_name": "Canada",
        "default": true
    }
    ],
    "admin_graphql_api_id": "gid://haravan/Customer/1073339457",
    "default_address": {
    "id": 1053317287,
    "customer_id": 1073339457,
    "first_name": "Mother",
    "last_name": "Lastnameson",
    "company": null,
    "address1": "123 Oak St",
    "address2": null,
    "city": "Ottawa",
    "province": "Ontario",
    "country": "Canada",
    "zip": "123 ABC",
    "phone": "555-1212",
    "name": "Mother Lastnameson",
    "province_code": "ON",
    "country_code": "CA",
    "country_name": "Canada",
    "default": true
    }
}
]
}

Retrieve all customers changed after a certain date

GET /com/customers.json?updated_at_min=2018-07-10 18:38:13
Hide response
HTTP/1.1 200 OK
{
"customers": [
{
    "id": 207119551,
    "email": "bob.norman@hostmail.com",
    "accepts_marketing": false,
    "created_at": "2018-07-11T14:37:16-04:00",
    "updated_at": "2018-07-11T14:37:16-04:00",
    "first_name": "Bob",
    "last_name": "Norman",
    "orders_count": 1,
    "state": "disabled",
    "total_spent": "41.94",
    "last_order_id": 450789469,
    "note": null,
    "verified_email": true,
    "multipass_identifier": null,
    "tax_exempt": false,
    "phone": null,
    "tags": "",
    "last_order_name": "#1001",
    "addresses": [
    {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
    }
    ],
    "admin_graphql_api_id": "gid://haravan/Customer/207119551",
    "default_address": {
    "id": 207119551,
    "customer_id": 207119551,
    "first_name": null,
    "last_name": null,
    "company": null,
    "address1": "Chestnut Street 92",
    "address2": "",
    "city": "Louisville",
    "province": "Kentucky",
    "country": "United States",
    "zip": "40202",
    "phone": "555-625-1199",
    "name": "",
    "province_code": "KY",
    "country_code": "US",
    "country_name": "United States",
    "default": true
    }
}
]
}

Retrieve a list of specific customers

GET /com/customers.json?ids=207119551,1073339458
Hide response
HTTP/1.1 200 OK
{
"customers": [
{
    "id": 1073339458,
    "email": "steve.lastnameson@example.com",
    "accepts_marketing": false,
    "created_at": "2018-07-11T14:38:15-04:00",
    "updated_at": "2018-07-11T14:38:15-04:00",
    "first_name": "Steve",
    "last_name": "Lastnameson",
    "orders_count": 0,
    "state": "disabled",
    "total_spent": "0.00",
    "last_order_id": null,
    "note": null,
    "verified_email": true,
    "multipass_identifier": null,
    "tax_exempt": false,
    "phone": "+15142546011",
    "tags": "",
    "last_order_name": null,
    "addresses": [
    {
        "id": 1053317288,
        "customer_id": 1073339458,
        "first_name": "Mother",
        "last_name": "Lastnameson",
        "company": null,
        "address1": "123 Oak St",
        "address2": null,
        "city": "Ottawa",
        "province": "Ontario",
        "country": "Canada",
        "zip": "123 ABC",
        "phone": "555-1212",
        "name": "Mother Lastnameson",
        "province_code": "ON",
        "country_code": "CA",
        "country_name": "Canada",
        "default": true
    }
    ],
    "admin_graphql_api_id": "gid://haravan/Customer/1073339458",
    "default_address": {
    "id": 1053317288,
    "customer_id": 1073339458,
    "first_name": "Mother",
    "last_name": "Lastnameson",
    "company": null,
    "address1": "123 Oak St",
    "address2": null,
    "city": "Ottawa",
    "province": "Ontario",
    "country": "Canada",
    "zip": "123 ABC",
    "phone": "555-1212",
    "name": "Mother Lastnameson",
    "province_code": "ON",
    "country_code": "CA",
    "country_name": "Canada",
    "default": true
    }
},
{
    "id": 207119551,
    "email": "bob.norman@hostmail.com",
    "accepts_marketing": false,
    "created_at": "2018-07-11T14:37:16-04:00",
    "updated_at": "2018-07-11T14:37:16-04:00",
    "first_name": "Bob",
    "last_name": "Norman",
    "orders_count": 1,
    "state": "disabled",
    "total_spent": "41.94",
    "last_order_id": 450789469,
    "note": null,
    "verified_email": true,
    "multipass_identifier": null,
    "tax_exempt": false,
    "phone": null,
    "tags": "",
    "last_order_name": "#1001",
    "addresses": [
    {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
    }
    ],
    "admin_graphql_api_id": "gid://haravan/Customer/207119551",
    "default_address": {
    "id": 207119551,
    "customer_id": 207119551,
    "first_name": null,
    "last_name": null,
    "company": null,
    "address1": "Chestnut Street 92",
    "address2": "",
    "city": "Louisville",
    "province": "Kentucky",
    "country": "United States",
    "zip": "40202",
    "phone": "555-625-1199",
    "name": "",
    "province_code": "KY",
    "country_code": "US",
    "country_name": "United States",
    "default": true
    }
}
]
}
GET/com/customers/207119551.json
Retrieves a single customer.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve a single customer by their ID

GET /com/customers/#{customer_id}.json
Hide response
HTTP/1.1 200 OK
{
"customer": {
"id": 207119551,
"email": "bob.norman@hostmail.com",
"accepts_marketing": false,
"created_at": "2018-07-11T14:37:16-04:00",
"updated_at": "2018-07-11T14:37:16-04:00",
"first_name": "Bob",
"last_name": "Norman",
"orders_count": 1,
"state": "disabled",
"total_spent": "41.94",
"last_order_id": 450789469,
"note": null,
"verified_email": true,
"multipass_identifier": null,
"tax_exempt": false,
"phone": null,
"tags": "",
"last_order_name": "#1001",
"addresses": [
    {
    "id": 207119551,
    "customer_id": 207119551,
    "first_name": null,
    "last_name": null,
    "company": null,
    "address1": "Chestnut Street 92",
    "address2": "",
    "city": "Louisville",
    "province": "Kentucky",
    "country": "United States",
    "zip": "40202",
    "phone": "555-625-1199",
    "name": "",
    "province_code": "KY",
    "country_code": "US",
    "country_name": "United States",
    "default": true
    }
],
"admin_graphql_api_id": "gid://haravan/Customer/207119551",
"default_address": {
    "id": 207119551,
    "customer_id": 207119551,
    "first_name": null,
    "last_name": null,
    "company": null,
    "address1": "Chestnut Street 92",
    "address2": "",
    "city": "Louisville",
    "province": "Kentucky",
    "country": "United States",
    "zip": "40202",
    "phone": "555-625-1199",
    "name": "",
    "province_code": "KY",
    "country_code": "US",
    "country_name": "United States",
    "default": true
}
}
}
POST/com/customers.json
Creates a customer.

Create a new customer record

POST /com/customers.json
{
"customer": {
"first_name": "Steve",
"last_name": "Lastnameson",
"email": "steve.lastnameson@example.com",
"phone": "+15142546011",
"verified_email": true,
"addresses": [
    {
    "address1": "123 Oak St",
    "city": "Ottawa",
    "province": "ON",
    "phone": "555-1212",
    "zip": "123 ABC",
    "last_name": "Lastnameson",
    "first_name": "Mother",
    "country": "CA"
    }
]
}
}
Hide response
HTTP/1.1 201 Created
{
"customer": {
"id": 1073339459,
"email": "steve.lastnameson@example.com",
"accepts_marketing": false,
"created_at": "2018-07-11T14:38:24-04:00",
"updated_at": "2018-07-11T14:38:24-04:00",
"first_name": "Steve",
"last_name": "Lastnameson",
"orders_count": 0,
"state": "disabled",
"total_spent": "0.00",
"last_order_id": null,
"note": null,
"verified_email": true,
"multipass_identifier": null,
"tax_exempt": false,
"phone": "+15142546011",
"tags": "",
"last_order_name": null,
"addresses": [
    {
    "id": 1053317289,
    "customer_id": 1073339459,
    "first_name": "Mother",
    "last_name": "Lastnameson",
    "company": null,
    "address1": "123 Oak St",
    "address2": null,
    "city": "Ottawa",
    "province": "Ontario",
    "country": "Canada",
    "zip": "123 ABC",
    "phone": "555-1212",
    "name": "Mother Lastnameson",
    "province_code": "ON",
    "country_code": "CA",
    "country_name": "Canada",
    "default": true
    }
],
"admin_graphql_api_id": "gid://haravan/Customer/1073339459",
"default_address": {
    "id": 1053317289,
    "customer_id": 1073339459,
    "first_name": "Mother",
    "last_name": "Lastnameson",
    "company": null,
    "address1": "123 Oak St",
    "address2": null,
    "city": "Ottawa",
    "province": "Ontario",
    "country": "Canada",
    "zip": "123 ABC",
    "phone": "555-1212",
    "name": "Mother Lastnameson",
    "province_code": "ON",
    "country_code": "CA",
    "country_name": "Canada",
    "default": true
}
}
}

Creating a customer without an email or name fails and returns an error

POST /com/customers.json
{
"customer": {
"email": null,
"first_name": null,
"last_name": null
}
}
Hide response
HTTP/1.1 422 Unprocessable Entity
{
"errors": {
"base": [
    "Customer must have a name, phone number or email address"
]
}
}

Create a customer with a metafield

POST /com/customers.json
{
"customer": {
"first_name": "Steve",
"last_name": "Lastnameson",
"email": "steve.lastnameson@example.com",
"phone": "+15142546011",
"verified_email": true,
"addresses": [
    {
    "address1": "123 Oak St",
    "city": "Ottawa",
    "province": "ON",
    "phone": "555-1212",
    "zip": "123 ABC",
    "last_name": "Lastnameson",
    "first_name": "Mother",
    "country": "CA"
    }
],
"metafields": [
    {
    "key": "new",
    "value": "newvalue",
    "value_type": "string",
    "namespace": "global"
    }
]
}
}
Hide response
HTTP/1.1 201 Created
{
"customer": {
"id": 1073339460,
"email": "steve.lastnameson@example.com",
"accepts_marketing": false,
"created_at": "2018-07-11T14:38:28-04:00",
"updated_at": "2018-07-11T14:38:28-04:00",
"first_name": "Steve",
"last_name": "Lastnameson",
"orders_count": 0,
"state": "disabled",
"total_spent": "0.00",
"last_order_id": null,
"note": null,
"verified_email": true,
"multipass_identifier": null,
"tax_exempt": false,
"phone": "+15142546011",
"tags": "",
"last_order_name": null,
"addresses": [
    {
    "id": 1053317290,
    "customer_id": 1073339460,
    "first_name": "Mother",
    "last_name": "Lastnameson",
    "company": null,
    "address1": "123 Oak St",
    "address2": null,
    "city": "Ottawa",
    "province": "Ontario",
    "country": "Canada",
    "zip": "123 ABC",
    "phone": "555-1212",
    "name": "Mother Lastnameson",
    "province_code": "ON",
    "country_code": "CA",
    "country_name": "Canada",
    "default": true
    }
],
"admin_graphql_api_id": "gid://haravan/Customer/1073339460",
"default_address": {
    "id": 1053317290,
    "customer_id": 1073339460,
    "first_name": "Mother",
    "last_name": "Lastnameson",
    "company": null,
    "address1": "123 Oak St",
    "address2": null,
    "city": "Ottawa",
    "province": "Ontario",
    "country": "Canada",
    "zip": "123 ABC",
    "phone": "555-1212",
    "name": "Mother Lastnameson",
    "province_code": "ON",
    "country_code": "CA",
    "country_name": "Canada",
    "default": true
}
}
}

Create a customer with send_email_invite

POST /com/customers.json
{
"customer": {
"first_name": "Steve",
"last_name": "Lastnameson",
"email": "steve.lastnameson@example.com",
"phone": "+15142546011",
"verified_email": true,
"addresses": [
    {
    "address1": "123 Oak St",
    "city": "Ottawa",
    "province": "ON",
    "phone": "555-1212",
    "zip": "123 ABC",
    "last_name": "Lastnameson",
    "first_name": "Mother",
    "country": "CA"
    }
],
"send_email_invite": true
}
}
Hide response
HTTP/1.1 201 Created
{
"customer": {
"id": 1073339461,
"email": "steve.lastnameson@example.com",
"accepts_marketing": false,
"created_at": "2018-07-11T14:38:30-04:00",
"updated_at": "2018-07-11T14:38:30-04:00",
"first_name": "Steve",
"last_name": "Lastnameson",
"orders_count": 0,
"state": "invited",
"total_spent": "0.00",
"last_order_id": null,
"note": null,
"verified_email": true,
"multipass_identifier": null,
"tax_exempt": false,
"phone": "+15142546011",
"tags": "",
"last_order_name": null,
"addresses": [
    {
    "id": 1053317291,
    "customer_id": 1073339461,
    "first_name": "Mother",
    "last_name": "Lastnameson",
    "company": null,
    "address1": "123 Oak St",
    "address2": null,
    "city": "Ottawa",
    "province": "Ontario",
    "country": "Canada",
    "zip": "123 ABC",
    "phone": "555-1212",
    "name": "Mother Lastnameson",
    "province_code": "ON",
    "country_code": "CA",
    "country_name": "Canada",
    "default": true
    }
],
"admin_graphql_api_id": "gid://haravan/Customer/1073339461",
"default_address": {
    "id": 1053317291,
    "customer_id": 1073339461,
    "first_name": "Mother",
    "last_name": "Lastnameson",
    "company": null,
    "address1": "123 Oak St",
    "address2": null,
    "city": "Ottawa",
    "province": "Ontario",
    "country": "Canada",
    "zip": "123 ABC",
    "phone": "555-1212",
    "name": "Mother Lastnameson",
    "province_code": "ON",
    "country_code": "CA",
    "country_name": "Canada",
    "default": true
}
}
}

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

POST /com/customers.json
{
"customer": {
"first_name": "Steve",
"last_name": "Lastnameson",
"email": "steve.lastnameson@example.com",
"phone": "+15142546011",
"verified_email": true,
"addresses": [
    {
    "address1": "123 Oak St",
    "city": "Ottawa",
    "province": "ON",
    "phone": "555-1212",
    "zip": "123 ABC",
    "last_name": "Lastnameson",
    "first_name": "Mother",
    "country": "CA"
    }
],
"password": "newpass",
"password_confirmation": "newpass",
"send_email_welcome": false
}
}
Hide response
HTTP/1.1 201 Created
{
"customer": {
"id": 1073339462,
"email": "steve.lastnameson@example.com",
"accepts_marketing": false,
"created_at": "2018-07-11T14:38:32-04:00",
"updated_at": "2018-07-11T14:38:32-04:00",
"first_name": "Steve",
"last_name": "Lastnameson",
"orders_count": 0,
"state": "enabled",
"total_spent": "0.00",
"last_order_id": null,
"note": null,
"verified_email": true,
"multipass_identifier": null,
"tax_exempt": false,
"phone": "+15142546011",
"tags": "",
"last_order_name": null,
"addresses": [
    {
    "id": 1053317292,
    "customer_id": 1073339462,
    "first_name": "Mother",
    "last_name": "Lastnameson",
    "company": null,
    "address1": "123 Oak St",
    "address2": null,
    "city": "Ottawa",
    "province": "Ontario",
    "country": "Canada",
    "zip": "123 ABC",
    "phone": "555-1212",
    "name": "Mother Lastnameson",
    "province_code": "ON",
    "country_code": "CA",
    "country_name": "Canada",
    "default": true
    }
],
"admin_graphql_api_id": "gid://haravan/Customer/1073339462",
"default_address": {
    "id": 1053317292,
    "customer_id": 1073339462,
    "first_name": "Mother",
    "last_name": "Lastnameson",
    "company": null,
    "address1": "123 Oak St",
    "address2": null,
    "city": "Ottawa",
    "province": "Ontario",
    "country": "Canada",
    "zip": "123 ABC",
    "phone": "555-1212",
    "name": "Mother Lastnameson",
    "province_code": "ON",
    "country_code": "CA",
    "country_name": "Canada",
    "default": true
}
}
}
PUT/com/customers/207119551.json
Updates a customer.

Update details for a customer

PUT /com/customers/#{customer_id}.json
{
"customer": {
"id": 207119551,
"email": "changed@email.address.com",
"note": "Customer is a great guy"
}
}
Hide response
HTTP/1.1 200 OK
{
"customer": {
"id": 207119551,
"email": "changed@email.address.com",
"accepts_marketing": false,
"created_at": "2018-07-11T14:37:16-04:00",
"updated_at": "2018-07-11T14:38:35-04:00",
"first_name": "Bob",
"last_name": "Norman",
"orders_count": 1,
"state": "disabled",
"total_spent": "41.94",
"last_order_id": 450789469,
"note": "Customer is a great guy",
"verified_email": true,
"multipass_identifier": null,
"tax_exempt": false,
"phone": null,
"tags": "",
"last_order_name": "#1001",
"addresses": [
    {
    "id": 207119551,
    "customer_id": 207119551,
    "first_name": null,
    "last_name": null,
    "company": null,
    "address1": "Chestnut Street 92",
    "address2": "",
    "city": "Louisville",
    "province": "Kentucky",
    "country": "United States",
    "zip": "40202",
    "phone": "555-625-1199",
    "name": "",
    "province_code": "KY",
    "country_code": "US",
    "country_name": "United States",
    "default": true
    }
],
"admin_graphql_api_id": "gid://haravan/Customer/207119551",
"default_address": {
    "id": 207119551,
    "customer_id": 207119551,
    "first_name": null,
    "last_name": null,
    "company": null,
    "address1": "Chestnut Street 92",
    "address2": "",
    "city": "Louisville",
    "province": "Kentucky",
    "country": "United States",
    "zip": "40202",
    "phone": "555-625-1199",
    "name": "",
    "province_code": "KY",
    "country_code": "US",
    "country_name": "United States",
    "default": true
}
}
}

Add metafield to an existing customer

PUT /com/customers/#{customer_id}.json
{
"customer": {
"id": 207119551,
"metafields": [
    {
    "key": "new",
    "value": "newvalue",
    "value_type": "string",
    "namespace": "global"
    }
]
}
}
Hide response
HTTP/1.1 200 OK
{
"customer": {
"id": 207119551,
"email": "bob.norman@hostmail.com",
"accepts_marketing": false,
"created_at": "2018-07-11T14:37:16-04:00",
"updated_at": "2018-07-11T14:38:38-04:00",
"first_name": "Bob",
"last_name": "Norman",
"orders_count": 1,
"state": "disabled",
"total_spent": "41.94",
"last_order_id": 450789469,
"note": null,
"verified_email": true,
"multipass_identifier": null,
"tax_exempt": false,
"phone": null,
"tags": "",
"last_order_name": "#1001",
"addresses": [
    {
    "id": 207119551,
    "customer_id": 207119551,
    "first_name": null,
    "last_name": null,
    "company": null,
    "address1": "Chestnut Street 92",
    "address2": "",
    "city": "Louisville",
    "province": "Kentucky",
    "country": "United States",
    "zip": "40202",
    "phone": "555-625-1199",
    "name": "",
    "province_code": "KY",
    "country_code": "US",
    "country_name": "United States",
    "default": true
    }
],
"admin_graphql_api_id": "gid://haravan/Customer/207119551",
"default_address": {
    "id": 207119551,
    "customer_id": 207119551,
    "first_name": null,
    "last_name": null,
    "company": null,
    "address1": "Chestnut Street 92",
    "address2": "",
    "city": "Louisville",
    "province": "Kentucky",
    "country": "United States",
    "zip": "40202",
    "phone": "555-625-1199",
    "name": "",
    "province_code": "KY",
    "country_code": "US",
    "country_name": "United States",
    "default": true
}
}
}

Update a customer's tags

PUT /com/customers/#{customer_id}.json
{
"customer": {
"id": 207119551,
"tags": "New Customer, Repeat Customer"
}
}
Hide response
HTTP/1.1 200 OK
{
"customer": {
"id": 207119551,
"email": "bob.norman@hostmail.com",
"accepts_marketing": false,
"created_at": "2018-07-11T14:37:16-04:00",
"updated_at": "2018-07-11T14:38:40-04:00",
"first_name": "Bob",
"last_name": "Norman",
"orders_count": 1,
"state": "disabled",
"total_spent": "41.94",
"last_order_id": 450789469,
"note": null,
"verified_email": true,
"multipass_identifier": null,
"tax_exempt": false,
"phone": null,
"tags": "New Customer, Repeat Customer",
"last_order_name": "#1001",
"addresses": [
    {
    "id": 207119551,
    "customer_id": 207119551,
    "first_name": null,
    "last_name": null,
    "company": null,
    "address1": "Chestnut Street 92",
    "address2": "",
    "city": "Louisville",
    "province": "Kentucky",
    "country": "United States",
    "zip": "40202",
    "phone": "555-625-1199",
    "name": "",
    "province_code": "KY",
    "country_code": "US",
    "country_name": "United States",
    "default": true
    }
],
"admin_graphql_api_id": "gid://haravan/Customer/207119551",
"default_address": {
    "id": 207119551,
    "customer_id": 207119551,
    "first_name": null,
    "last_name": null,
    "company": null,
    "address1": "Chestnut Street 92",
    "address2": "",
    "city": "Louisville",
    "province": "Kentucky",
    "country": "United States",
    "zip": "40202",
    "phone": "555-625-1199",
    "name": "",
    "province_code": "KY",
    "country_code": "US",
    "country_name": "United States",
    "default": true
}
}
}
POST/com/customers/207119551/account_activation_url.json

Generate an account activation URL for a customer whose account is not yet enabled. This is useful when you've imported a large number of customers and want to send them activation emails all at once. Using this approach, you'll need to generate and send the activation emails yourself.

The account activation URL generated by this endpoint is for one-time use and will expire after seven days. If you make a new POST request to this endpoint, then a new URL will be generated. The new URL will be again valid for 7 days, but the previous URL will no longer be valid.


Create an account activation URL for an invited or disabled customer

POST /com/customers/#{customer_id}/account_activation_url.json
{
}
Hide response
HTTP/1.1 200 OK
{
"account_activation_url": "https://apple.myharavan.com/account/activate/207119551/02e165b1fb50723f97bc0a10f6d153cd-1531334323"
}

Creating an account activation URL for an enabled customer fails and returns an error

POST /com/customers/#{customer_id}/account_activation_url.json
{
}
Hide response
HTTP/1.1 422 Unprocessable Entity
{
"errors": [
"account already active"
]
}
POST/com/customers/207119551/send_invite.json
Sends an account invite to a customer.

Send the default invite

POST /com/customers/#{customer_id}/send_invite.json
{
"customer_invite": {}
}
Hide response
HTTP/1.1 201 Created
{
"customer_invite": {
"to": "bob.norman@hostmail.com",
"from": "steve@apple.com",
"subject": "Customer account activation",
"custom_message": "",
"bcc": []
}
}

Send a customized invite

POST /com/customers/#{customer_id}/send_invite.json
{
"customer_invite": {
"to": "new_test_email@haravan.com",
"from": "noaccesssteve@jobs.com",
"bcc": [
    "noaccesssteve@jobs.com"
],
"subject": "Welcome to my new shop",
"custom_message": "My awesome new store"
}
}
Hide response
HTTP/1.1 201 Created
{
"customer_invite": {
"to": "new_test_email@haravan.com",
"from": "noaccesssteve@jobs.com",
"subject": "Welcome to my new shop",
"custom_message": "My awesome new store",
"bcc": [
    "noaccesssteve@jobs.com"
]
}
}
DELETE/com/customers/207119551.json
Deletes a customer. A customer can't be deleted if they have existing orders.

Remove an existing customer

DELETE /com/customers/#{customer_id}.json
Hide response
HTTP/1.1 422 Unprocessable Entity
{
"errors": "Error deleting customer"
}
GET/com/customers/count.json
Retrieves a count of all customers.

Retrieve a count of all customers

GET /com/customers/count.json
Hide response
HTTP/1.1 200 OK
{
"count": 1
}
GET
Retrieves all orders belonging to a customer.

Retrieve all orders from a customer

GET /com/customers/#{customer_id}/orders.json
Hide response
HTTP/1.1 200 OK
{
"orders": [
{
    "id": 450789469,
    "email": "bob.norman@hostmail.com",
    "closed_at": null,
    "created_at": "2008-01-10T11:00:00-05:00",
    "updated_at": "2008-01-10T11:00:00-05:00",
    "number": 1,
    "note": null,
    "token": "b1946ac92492d2347c6235b4d2611184",
    "gateway": "authorize_net",
    "test": false,
    "total_price": "409.94",
    "subtotal_price": "398.00",
    "total_weight": 0,
    "total_tax": "11.94",
    "taxes_included": false,
    "currency": "USD",
    "financial_status": "authorized",
    "confirmed": false,
    "total_discounts": "0.00",
    "total_line_items_price": "398.00",
    "cart_token": "68778783ad298f1c80c3bafcddeea02f",
    "buyer_accepts_marketing": false,
    "name": "#1001",
    "referring_site": "http://www.otherexample.com",
    "landing_site": "http://www.example.com?source=abc",
    "cancelled_at": null,
    "cancel_reason": null,
    "total_price_usd": "409.94",
    "checkout_token": "bd5a8aa1ecd019dd3520ff791ee3a24c",
    "reference": "fhwdgads",
    "user_id": null,
    "location_id": null,
    "source_identifier": "fhwdgads",
    "source_url": null,
    "processed_at": "2008-01-10T11:00:00-05:00",
    "device_id": null,
    "phone": "+557734881234",
    "customer_locale": null,
    "app_id": null,
    "browser_ip": null,
    "landing_site_ref": null,
    "order_number": 1001,
    "discount_applications": [
    {
        "type": "discount_code",
        "value": "10.0",
        "value_type": "percentage",
        "allocation_method": "across",
        "target_selection": "all",
        "target_type": "line_item",
        "code": "TENOFF"
    }
    ],
    "discount_codes": [
    {
        "code": "TENOFF",
        "amount": "10.00",
        "type": "percentage"
    }
    ],
    "note_attributes": [
    {
        "name": "custom engraving",
        "value": "Happy Birthday"
    },
    {
        "name": "colour",
        "value": "green"
    }
    ],
    "payment_gateway_names": [
    "bogus"
    ],
    "processing_method": "direct",
    "checkout_id": 901414060,
    "source_name": "web",
    "fulfillment_status": null,
    "tax_lines": [
    {
        "price": "11.94",
        "rate": 0.06,
        "title": "State Tax"
    }
    ],
    "tags": "",
    "contact_email": "bob.norman@hostmail.com",
    "order_status_url": "https://checkout.local/690933842/orders/b1946ac92492d2347c6235b4d2611184/authenticate?key=caa4c887469926d9977426614ca56f15",
    "admin_graphql_api_id": "gid://haravan/Order/450789469",
    "line_items": [
    {
        "id": 466157049,
        "variant_id": 39072856,
        "title": "IPod Nano - 8gb",
        "quantity": 1,
        "price": "199.00",
        "sku": "IPOD2008GREEN",
        "variant_title": "green",
        "vendor": null,
        "fulfillment_service": "manual",
        "product_id": 632910392,
        "requires_shipping": true,
        "taxable": true,
        "gift_card": false,
        "name": "IPod Nano - 8gb - green",
        "variant_inventory_management": "haravan",
        "properties": [
        {
            "name": "Custom Engraving Front",
            "value": "Happy Birthday"
        },
        {
            "name": "Custom Engraving Back",
            "value": "Merry Christmas"
        }
        ],
        "product_exists": true,
        "fulfillable_quantity": 1,
        "grams": 200,
        "total_discount": "0.00",
        "fulfillment_status": null,
        "discount_allocations": [],
        "admin_graphql_api_id": "gid://haravan/LineItem/466157049",
        "tax_lines": [
        {
            "title": "State Tax",
            "price": "3.98",
            "rate": 0.06
        }
        ]
    },
    {
        "id": 518995019,
        "variant_id": 49148385,
        "title": "IPod Nano - 8gb",
        "quantity": 1,
        "price": "199.00",
        "sku": "IPOD2008RED",
        "variant_title": "red",
        "vendor": null,
        "fulfillment_service": "manual",
        "product_id": 632910392,
        "requires_shipping": true,
        "taxable": true,
        "gift_card": false,
        "name": "IPod Nano - 8gb - red",
        "variant_inventory_management": "haravan",
        "properties": [],
        "product_exists": true,
        "fulfillable_quantity": 1,
        "grams": 200,
        "total_discount": "0.00",
        "fulfillment_status": null,
        "discount_allocations": [],
        "admin_graphql_api_id": "gid://haravan/LineItem/518995019",
        "tax_lines": [
        {
            "title": "State Tax",
            "price": "3.98",
            "rate": 0.06
        }
        ]
    },
    {
        "id": 703073504,
        "variant_id": 457924702,
        "title": "IPod Nano - 8gb",
        "quantity": 1,
        "price": "199.00",
        "sku": "IPOD2008BLACK",
        "variant_title": "black",
        "vendor": null,
        "fulfillment_service": "manual",
        "product_id": 632910392,
        "requires_shipping": true,
        "taxable": true,
        "gift_card": false,
        "name": "IPod Nano - 8gb - black",
        "variant_inventory_management": "haravan",
        "properties": [],
        "product_exists": true,
        "fulfillable_quantity": 1,
        "grams": 200,
        "total_discount": "0.00",
        "fulfillment_status": null,
        "discount_allocations": [],
        "admin_graphql_api_id": "gid://haravan/LineItem/703073504",
        "tax_lines": [
        {
            "title": "State Tax",
            "price": "3.98",
            "rate": 0.06
        }
        ]
    }
    ],
    "shipping_lines": [
    {
        "id": 369256396,
        "title": "Free Shipping",
        "price": "0.00",
        "code": "Free Shipping",
        "source": "haravan",
        "phone": null,
        "requested_fulfillment_service_id": null,
        "delivery_category": null,
        "carrier_identifier": null,
        "discounted_price": "0.00",
        "discount_allocations": [],
        "tax_lines": []
    }
    ],
    "billing_address": {
    "first_name": "Bob",
    "address1": "Chestnut Street 92",
    "phone": "555-625-1199",
    "city": "Louisville",
    "zip": "40202",
    "province": "Kentucky",
    "country": "United States",
    "last_name": "Norman",
    "address2": "",
    "company": null,
    "latitude": 45.41634,
    "longitude": -75.6868,
    "name": "Bob Norman",
    "country_code": "US",
    "province_code": "KY"
    },
    "shipping_address": {
    "first_name": "Bob",
    "address1": "Chestnut Street 92",
    "phone": "555-625-1199",
    "city": "Louisville",
    "zip": "40202",
    "province": "Kentucky",
    "country": "United States",
    "last_name": "Norman",
    "address2": "",
    "company": null,
    "latitude": 45.41634,
    "longitude": -75.6868,
    "name": "Bob Norman",
    "country_code": "US",
    "province_code": "KY"
    },
    "fulfillments": [
    {
        "id": 255858046,
        "order_id": 450789469,
        "status": "failure",
        "created_at": "2018-07-11T14:37:16-04:00",
        "service": "manual",
        "updated_at": "2018-07-11T14:37:16-04:00",
        "tracking_company": null,
        "shipment_status": null,
        "location_id": 905684977,
        "tracking_number": "1Z2345",
        "tracking_numbers": [
        "1Z2345"
        ],
        "tracking_url": "http://wwwapps.ups.com/etracking/tracking.cgi?InquiryNumber1=1Z2345TypeOfInquiryNumber=TAcceptUPSLicenseAgreement=yessubmit=Track",
        "tracking_urls": [
        "http://wwwapps.ups.com/etracking/tracking.cgi?InquiryNumber1=1Z2345TypeOfInquiryNumber=TAcceptUPSLicenseAgreement=yessubmit=Track"
        ],
        "receipt": {
        "testcase": true,
        "authorization": "123456"
        },
        "name": "#1001.0",
        "admin_graphql_api_id": "gid://haravan/Fulfillment/255858046",
        "line_items": [
        {
            "id": 466157049,
            "variant_id": 39072856,
            "title": "IPod Nano - 8gb",
            "quantity": 1,
            "price": "199.00",
            "sku": "IPOD2008GREEN",
            "variant_title": "green",
            "vendor": null,
            "fulfillment_service": "manual",
            "product_id": 632910392,
            "requires_shipping": true,
            "taxable": true,
            "gift_card": false,
            "name": "IPod Nano - 8gb - green",
            "variant_inventory_management": "haravan",
            "properties": [
            {
                "name": "Custom Engraving Front",
                "value": "Happy Birthday"
            },
            {
                "name": "Custom Engraving Back",
                "value": "Merry Christmas"
            }
            ],
            "product_exists": true,
            "fulfillable_quantity": 1,
            "grams": 200,
            "total_discount": "0.00",
            "fulfillment_status": null,
            "discount_allocations": [],
            "admin_graphql_api_id": "gid://haravan/LineItem/466157049",
            "tax_lines": [
            {
                "title": "State Tax",
                "price": "3.98",
                "rate": 0.06
            }
            ]
        }
        ]
    }
    ],
    "client_details": {
    "browser_ip": "0.0.0.0",
    "accept_language": null,
    "user_agent": null,
    "session_hash": null,
    "browser_width": null,
    "browser_height": null
    },
    "refunds": [
    {
        "id": 509562969,
        "order_id": 450789469,
        "created_at": "2018-07-11T14:37:16-04:00",
        "note": "it broke during shipping",
        "user_id": 799407056,
        "processed_at": "2018-07-11T14:37:16-04:00",
        "restock": true,
        "admin_graphql_api_id": "gid://haravan/Refund/509562969",
        "refund_line_items": [
        {
            "id": 104689539,
            "quantity": 1,
            "line_item_id": 703073504,
            "location_id": 487838322,
            "restock_type": "legacy_restock",
            "subtotal": 195.67,
            "total_tax": 3.98,
            "line_item": {
            "id": 703073504,
            "variant_id": 457924702,
            "title": "IPod Nano - 8gb",
            "quantity": 1,
            "price": "199.00",
            "sku": "IPOD2008BLACK",
            "variant_title": "black",
            "vendor": null,
            "fulfillment_service": "manual",
            "product_id": 632910392,
            "requires_shipping": true,
            "taxable": true,
            "gift_card": false,
            "name": "IPod Nano - 8gb - black",
            "variant_inventory_management": "haravan",
            "properties": [],
            "product_exists": true,
            "fulfillable_quantity": 1,
            "grams": 200,
            "total_discount": "0.00",
            "fulfillment_status": null,
            "discount_allocations": [],
            "admin_graphql_api_id": "gid://haravan/LineItem/703073504",
            "tax_lines": [
                {
                "title": "State Tax",
                "price": "3.98",
                "rate": 0.06
                }
            ]
            }
        },
        {
            "id": 709875399,
            "quantity": 1,
            "line_item_id": 466157049,
            "location_id": 487838322,
            "restock_type": "legacy_restock",
            "subtotal": 195.66,
            "total_tax": 3.98,
            "line_item": {
            "id": 466157049,
            "variant_id": 39072856,
            "title": "IPod Nano - 8gb",
            "quantity": 1,
            "price": "199.00",
            "sku": "IPOD2008GREEN",
            "variant_title": "green",
            "vendor": null,
            "fulfillment_service": "manual",
            "product_id": 632910392,
            "requires_shipping": true,
            "taxable": true,
            "gift_card": false,
            "name": "IPod Nano - 8gb - green",
            "variant_inventory_management": "haravan",
            "properties": [
                {
                "name": "Custom Engraving Front",
                "value": "Happy Birthday"
                },
                {
                "name": "Custom Engraving Back",
                "value": "Merry Christmas"
                }
            ],
            "product_exists": true,
            "fulfillable_quantity": 1,
            "grams": 200,
            "total_discount": "0.00",
            "fulfillment_status": null,
            "discount_allocations": [],
            "admin_graphql_api_id": "gid://haravan/LineItem/466157049",
            "tax_lines": [
                {
                "title": "State Tax",
                "price": "3.98",
                "rate": 0.06
                }
            ]
            }
        }
        ],
        "transactions": [
        {
            "id": 179259969,
            "order_id": 450789469,
            "amount": "209.00",
            "kind": "refund",
            "gateway": "bogus",
            "status": "success",
            "message": null,
            "created_at": "2005-08-05T12:59:12-04:00",
            "test": false,
            "authorization": "authorization-key",
            "currency": "USD",
            "location_id": null,
            "user_id": null,
            "parent_id": 801038806,
            "device_id": null,
            "receipt": {},
            "error_code": null,
            "source_name": "web",
            "admin_graphql_api_id": "gid://haravan/OrderTransaction/179259969"
        }
        ],
        "order_adjustments": []
    }
    ],
    "payment_details": {
    "credit_card_bin": null,
    "avs_result_code": null,
    "cvv_result_code": null,
    "credit_card_number": "•••• •••• •••• 4242",
    "credit_card_company": "Visa"
    },
    "customer": {
    "id": 207119551,
    "email": "bob.norman@hostmail.com",
    "accepts_marketing": false,
    "created_at": "2018-07-11T14:37:16-04:00",
    "updated_at": "2018-07-11T14:37:16-04:00",
    "first_name": "Bob",
    "last_name": "Norman",
    "orders_count": 1,
    "state": "disabled",
    "total_spent": "41.94",
    "last_order_id": 450789469,
    "note": null,
    "verified_email": true,
    "multipass_identifier": null,
    "tax_exempt": false,
    "phone": null,
    "tags": "",
    "last_order_name": "#1001",
    "admin_graphql_api_id": "gid://haravan/Customer/207119551",
    "default_address": {
        "id": 207119551,
        "customer_id": 207119551,
        "first_name": null,
        "last_name": null,
        "company": null,
        "address1": "Chestnut Street 92",
        "address2": "",
        "city": "Louisville",
        "province": "Kentucky",
        "country": "United States",
        "zip": "40202",
        "phone": "555-625-1199",
        "name": "",
        "province_code": "KY",
        "country_code": "US",
        "country_name": "United States",
        "default": true
    }
    }
}
]
}