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 resource instance does not store credit card information. Customers will always have to provide this information at checkout.

Customer

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 create 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 Shopify 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's account in a shop. The state can be changed in the shop admin or by the customer, but not through the API. Valid states are:

  • disabled: customers are disabled by default until they are invited. Staff accounts can disable a customer's account at any time.
  • invited: the customer has been emailed an invite to create an account that saves their customer settings.
  • enabled: the customer accepted the email invite and created an account.
  • declined: the customer declined the email invite to create an account.

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.

tax_exempt
{ "tax_exempt" : true }

Indicates whether the customer should be charged taxes when placing orders. Valid values are "true" and "false."

total_spent
{ "total_spent" : "0.00" }

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

ids

A comma-separated list of customer ids

since_id

Restrict results to after the specified ID

created_at_min

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

created_at_max

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

updated_at_min

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

updated_at_max

Show customers last updated before date (format: 2014-04-25T16:15:47-04: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 a list of specific customers

GET /admin/customers.json?ids=207119551,1073339503
View Response
              HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": 1073339503,
      "email": "steve.lastnameson@example.com",
      "accepts_marketing": false,
      "created_at": "2016-08-26T13:33:17-04:00",
      "updated_at": "2016-08-26T13:33:17-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,
      "tags": "",
      "last_order_name": null,
      "default_address": {
        "id": 1053317351,
        "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
      },
      "addresses": [
        {
          "id": 1053317351,
          "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": "2016-08-26T13:33:13-04:00",
      "updated_at": "2016-08-26T13:33:13-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,
      "tags": "",
      "last_order_name": "#1001",
      "default_address": {
        "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
      },
      "addresses": [
        {
          "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 all customers for a shop

GET /admin/customers.json
View Response
              HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": false,
      "created_at": "2016-08-26T13:33:18-04:00",
      "updated_at": "2016-08-26T13:33:18-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,
      "tags": "",
      "last_order_name": "#1001",
      "default_address": {
        "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
      },
      "addresses": [
        {
          "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 all customers for a shop changed after a certain date

GET /admin/customers.json?updated_at_min=2016-08-25 17:34:19
View Response
              HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": false,
      "created_at": "2016-08-26T13:34:15-04:00",
      "updated_at": "2016-08-26T13:34:15-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,
      "tags": "",
      "last_order_name": "#1001",
      "default_address": {
        "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
      },
      "addresses": [
        {
          "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 all customers for a shop after a specified ID

GET /admin/customers.json?since_id=207119551
View Response
              HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": 1073339508,
      "email": "steve.lastnameson@example.com",
      "accepts_marketing": false,
      "created_at": "2016-08-26T13:34:24-04:00",
      "updated_at": "2016-08-26T13:34: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,
      "tags": "",
      "last_order_name": null,
      "default_address": {
        "id": 1053317356,
        "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
      },
      "addresses": [
        {
          "id": 1053317356,
          "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
        }
      ]
    }
  ]
}
            
GET /admin/customers/207119551.json
fields

comma-separated list of fields to include in the response

Get a single customer by ID

GET /admin/customers/#{id}.json
View Response
              HTTP/1.1 200 OK
{
  "customer": {
    "id": 207119551,
    "email": "bob.norman@hostmail.com",
    "accepts_marketing": false,
    "created_at": "2016-08-26T13:33:51-04:00",
    "updated_at": "2016-08-26T13:33:51-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,
    "tags": "",
    "last_order_name": "#1001",
    "default_address": {
      "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
    },
    "addresses": [
      {
        "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 /admin/customers.json

Trying to create a customer without an email or name will return an error

POST /admin/customers.json
                {
  "customer": {
    "email": null,
    "first_name": null,
    "last_name": null
  }
}
              
View Response
              HTTP/1.1 422 Unprocessable Entity
{
  "customer": {
    "id": null,
    "email": null,
    "accepts_marketing": false,
    "created_at": null,
    "updated_at": null,
    "first_name": null,
    "last_name": null,
    "orders_count": 0,
    "state": "disabled",
    "total_spent": "0.00",
    "last_order_id": null,
    "note": null,
    "verified_email": true,
    "multipass_identifier": null,
    "tax_exempt": false,
    "tags": "",
    "last_order_name": null,
    "addresses": [
    ]
  },
  "errors": {
    "base": [
      "Customer must have a name or email address"
    ]
  }
}
            

Create a new customer record

POST /admin/customers.json
                {
  "customer": {
    "first_name": "Steve",
    "last_name": "Lastnameson",
    "email": "steve.lastnameson@example.com",
    "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"
      }
    ]
  }
}
              
View Response
              HTTP/1.1 201 Created
{
  "customer": {
    "id": 1073339504,
    "email": "steve.lastnameson@example.com",
    "accepts_marketing": false,
    "created_at": "2016-08-26T13:33:36-04:00",
    "updated_at": "2016-08-26T13:33:36-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,
    "tags": "",
    "last_order_name": null,
    "default_address": {
      "id": 1053317352,
      "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
    },
    "addresses": [
      {
        "id": 1053317352,
        "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 new customer with password and password_confirmation and skip sending the welcome email

POST /admin/customers.json
                {
  "customer": {
    "first_name": "Steve",
    "last_name": "Lastnameson",
    "email": "steve.lastnameson@example.com",
    "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
  }
}
              
View Response
              HTTP/1.1 201 Created
{
  "customer": {
    "id": 1073339506,
    "email": "steve.lastnameson@example.com",
    "accepts_marketing": false,
    "created_at": "2016-08-26T13:33:45-04:00",
    "updated_at": "2016-08-26T13:33:45-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,
    "tags": "",
    "last_order_name": null,
    "default_address": {
      "id": 1053317354,
      "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
    },
    "addresses": [
      {
        "id": 1053317354,
        "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 new customer with a metafield

POST /admin/customers.json
                {
  "customer": {
    "first_name": "Steve",
    "last_name": "Lastnameson",
    "email": "steve.lastnameson@example.com",
    "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"
      }
    ]
  }
}
              
View Response
              HTTP/1.1 201 Created
{
  "customer": {
    "id": 1073339507,
    "email": "steve.lastnameson@example.com",
    "accepts_marketing": false,
    "created_at": "2016-08-26T13:34:14-04:00",
    "updated_at": "2016-08-26T13:34: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,
    "tags": "",
    "last_order_name": null,
    "default_address": {
      "id": 1053317355,
      "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
    },
    "addresses": [
      {
        "id": 1053317355,
        "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 new customer with send_email_invite

POST /admin/customers.json
                {
  "customer": {
    "first_name": "Steve",
    "last_name": "Lastnameson",
    "email": "steve.lastnameson@example.com",
    "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
  }
}
              
View Response
              HTTP/1.1 201 Created
{
  "customer": {
    "id": 1073339509,
    "email": "steve.lastnameson@example.com",
    "accepts_marketing": false,
    "created_at": "2016-08-26T13:34:53-04:00",
    "updated_at": "2016-08-26T13:34:53-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,
    "tags": "",
    "last_order_name": null,
    "default_address": {
      "id": 1053317357,
      "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
    },
    "addresses": [
      {
        "id": 1053317357,
        "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 /admin/customers/207119551.json

Add metafield to an existing customer

PUT /admin/customers/#{id}.json
                {
  "customer": {
    "id": 207119551,
    "metafields": [
      {
        "key": "new",
        "value": "newvalue",
        "value_type": "string",
        "namespace": "global"
      }
    ]
  }
}
              
View Response
              HTTP/1.1 200 OK
{
  "customer": {
    "id": 207119551,
    "email": "bob.norman@hostmail.com",
    "accepts_marketing": false,
    "created_at": "2016-08-26T13:34:24-04:00",
    "updated_at": "2016-08-26T13:34:29-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,
    "tags": "",
    "last_order_name": "#1001",
    "default_address": {
      "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
    },
    "addresses": [
      {
        "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 /admin/customers/#{id}.json
                {
  "customer": {
    "id": 207119551,
    "tags": "New Customer, Repeat Customer"
  }
}
              
View Response
              HTTP/1.1 200 OK
{
  "customer": {
    "id": 207119551,
    "email": "bob.norman@hostmail.com",
    "accepts_marketing": false,
    "created_at": "2016-08-26T13:34:38-04:00",
    "updated_at": "2016-08-26T13:34:43-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,
    "tags": "New Customer, Repeat Customer",
    "last_order_name": "#1001",
    "default_address": {
      "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
    },
    "addresses": [
      {
        "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 details for a customer

PUT /admin/customers/#{id}.json
                {
  "customer": {
    "id": 207119551,
    "email": "changed@email.address.com",
    "note": "Customer is a great guy"
  }
}
              
View Response
              HTTP/1.1 200 OK
{
  "customer": {
    "id": 207119551,
    "email": "changed@email.address.com",
    "accepts_marketing": false,
    "created_at": "2016-08-26T13:34:43-04:00",
    "updated_at": "2016-08-26T13:34:48-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,
    "tags": "",
    "last_order_name": "#1001",
    "default_address": {
      "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
    },
    "addresses": [
      {
        "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 /admin/customers/207119551/account_activation_url.json

This endpoint allows you to generate and retrieve an account activation URL for a customer who is not yet enabled. This is useful if 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 one time use and will expire after 7 days. If you make a new POST request to this endpoint, a new URL will be generated which will be again valid for 7 days, but the previous URL will no longer be valid.

Attempting to create an account activation URL for an enabled customer returns an error

POST /admin/customers/#{id}/account_activation_url.json
                {
  "customer": {
    "id": 207119551
  }
}
              
View Response
              HTTP/1.1 422 Unprocessable Entity
{
  "errors": [
    "account already active"
  ]
}
            

Create account activation URL for an invited or disabled customer

POST /admin/customers/#{id}/account_activation_url.json
                {
  "customer": {
    "id": 207119551
  }
}
              
View Response
              HTTP/1.1 200 OK
{
  "account_activation_url": "http:\/\/apple.myshopify.com\/account\/activate\/207119551\/59a56e45ba7e044c20991eea011fb437-1472232850"
}
            
DELETE /admin/customers/207119551.json

Delete a customer. A customer can't be deleted if they have existing orders

Remove an existing customer

DELETE /admin/customers/#{id}.json
View Response
              HTTP/1.1 200 OK
{}
            
GET /admin/customers/count.json

Get a count of all customers

Get count of all customers for a shop

GET /admin/customers/count.json
View Response
              HTTP/1.1 200 OK
{
  "count": 1
}
            
GET /admin/orders.json

Get all orders belonging to this customer

Get all orders from this customer in this shop

GET /admin/orders.json?customer_id=207119551
View 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": null,
      "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,
      "browser_ip": null,
      "landing_site_ref": "abc",
      "order_number": 1001,
      "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": 450789469,
      "source_name": "web",
      "fulfillment_status": null,
      "tax_lines": [
        {
          "title": "State Tax",
          "price": "11.94",
          "rate": 0.06
        }
      ],
      "tags": "",
      "contact_email": "bob.norman@hostmail.com",
      "order_status_url": null,
      "line_items": [
        {
          "id": 466157049,
          "variant_id": 39072856,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "price": "199.00",
          "grams": 200,
          "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": "shopify",
          "properties": [
            {
              "name": "Custom Engraving Front",
              "value": "Happy Birthday"
            },
            {
              "name": "Custom Engraving Back",
              "value": "Merry Christmas"
            }
          ],
          "product_exists": true,
          "fulfillable_quantity": 1,
          "total_discount": "0.00",
          "fulfillment_status": null,
          "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",
          "grams": 200,
          "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": "shopify",
          "properties": [
          ],
          "product_exists": true,
          "fulfillable_quantity": 1,
          "total_discount": "0.00",
          "fulfillment_status": null,
          "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",
          "grams": 200,
          "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": "shopify",
          "properties": [
          ],
          "product_exists": true,
          "fulfillable_quantity": 1,
          "total_discount": "0.00",
          "fulfillment_status": null,
          "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": "shopify",
          "phone": null,
          "requested_fulfillment_service_id": null,
          "delivery_category": null,
          "carrier_identifier": null,
          "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": "2016-08-26T13:34:34-04:00",
          "service": "manual",
          "updated_at": "2016-08-26T13:34:34-04:00",
          "tracking_company": null,
          "shipment_status": null,
          "tracking_number": "1Z2345",
          "tracking_numbers": [
            "1Z2345"
          ],
          "tracking_url": "http:\/\/wwwapps.ups.com\/etracking\/tracking.cgi?InquiryNumber1=1Z2345&TypeOfInquiryNumber=T&AcceptUPSLicenseAgreement=yes&submit=Track",
          "tracking_urls": [
            "http:\/\/wwwapps.ups.com\/etracking\/tracking.cgi?InquiryNumber1=1Z2345&TypeOfInquiryNumber=T&AcceptUPSLicenseAgreement=yes&submit=Track"
          ],
          "receipt": {
            "testcase": true,
            "authorization": "123456"
          },
          "line_items": [
            {
              "id": 466157049,
              "variant_id": 39072856,
              "title": "IPod Nano - 8gb",
              "quantity": 1,
              "price": "199.00",
              "grams": 200,
              "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": "shopify",
              "properties": [
                {
                  "name": "Custom Engraving Front",
                  "value": "Happy Birthday"
                },
                {
                  "name": "Custom Engraving Back",
                  "value": "Merry Christmas"
                }
              ],
              "product_exists": true,
              "fulfillable_quantity": 1,
              "total_discount": "0.00",
              "fulfillment_status": null,
              "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": "2016-08-26T13:34:34-04:00",
          "note": "it broke during shipping",
          "restock": true,
          "user_id": 799407056,
          "refund_line_items": [
            {
              "id": 104689539,
              "quantity": 1,
              "line_item_id": 703073504,
              "line_item": {
                "id": 703073504,
                "variant_id": 457924702,
                "title": "IPod Nano - 8gb",
                "quantity": 1,
                "price": "199.00",
                "grams": 200,
                "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": "shopify",
                "properties": [
                ],
                "product_exists": true,
                "fulfillable_quantity": 1,
                "total_discount": "0.00",
                "fulfillment_status": null,
                "tax_lines": [
                  {
                    "title": "State Tax",
                    "price": "3.98",
                    "rate": 0.06
                  }
                ]
              }
            },
            {
              "id": 709875399,
              "quantity": 1,
              "line_item_id": 466157049,
              "line_item": {
                "id": 466157049,
                "variant_id": 39072856,
                "title": "IPod Nano - 8gb",
                "quantity": 1,
                "price": "199.00",
                "grams": 200,
                "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": "shopify",
                "properties": [
                  {
                    "name": "Custom Engraving Front",
                    "value": "Happy Birthday"
                  },
                  {
                    "name": "Custom Engraving Back",
                    "value": "Merry Christmas"
                  }
                ],
                "product_exists": true,
                "fulfillable_quantity": 1,
                "total_discount": "0.00",
                "fulfillment_status": null,
                "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": null,
              "device_id": null,
              "receipt": {},
              "error_code": null,
              "source_name": "web"
            }
          ],
          "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": "2016-08-26T13:34:34-04:00",
        "updated_at": "2016-08-26T13:34:34-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,
        "tags": "",
        "last_order_name": "#1001",
        "default_address": {
          "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
        }
      }
    }
  ]
}