API version: unstable
API version: 2021-04 Release candidate
API version: 2021-01 Latest
API version: 2020-10
API version: 2020-07
API version: 2020-04
API version: 2020-01 Unsupported
API version: 2019-10 Unsupported

Customer

Version 2020-01

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 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

Whether the customer has consented to receive marketing material via email.
accepts_marketing_updated_at 
"accepts_marketing_updated_at": "2013-06-27T08:48:27-04:00"

The date and time (ISO 8601 format) when the customer consented or objected to receiving marketing material by email. Set this value whenever the customer consents or objects to marketing materials.
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 code for the region of the address, such as the province, state, or district. For example QC for Quebec, Canada.
  • zip: The customer's postal code, also known as zip, postcode, Eircode, etc.
currency
read-only 
"currency": "JPY"

The three-letter code (ISO 4217 format) for the currency that the customer used when they paid for their last order. Defaults to the shop currency. Returns the shop currency for test orders.

created_at
read-only 
"created_at": "2013-06-27T08:48:27-04:00"

The date and time (ISO 8601 format) when the customer was created.
default_address
read-only 
"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
read-only 
"last_order_id": 234132602919

The ID of the customer's last order.
last_order_name
read-only 
"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.
marketing_opt_in_level
read-only 
"marketing_opt_in_level": "single_opt_in"

The marketing subscription opt-in level (as described by the M3AAWG best practices guideline) that the customer gave when they consented to receive marketing material by email. If the customer does not accept email marketing, then this property will be set to null. Valid values:

  • single_opt_in
  • confirmed_opt_in
  • unknown
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
read-only 
"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
read-only 
"state": "disabled"

The state of the customer's account with a shop. Default value: disabled. Valid values:

  • disabled: The customer doesn't have an active account. Customer accounts can be disabled from the Shopify admin at any time.
  • invited: The customer has received an email 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. A customer can have up to 250 tags. Each tag can have up to 255 characters.
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.
tax_exemptions 
"tax_exemptions": [
  "CA_STATUS_CARD_EXEMPTION",
  "CA_BC_RESELLER_EXEMPTION"
]

Whether the customer is exempt from paying specific taxes on their order. Canadian taxes only. Valid values:

  • EXEMPT_ALL: This customer is exempt from all Canadian taxes.
  • CA_STATUS_CARD_EXEMPTION: This customer is exempt from specific taxes for holding a valid STATUS_CARD_EXEMPTION in Canada.
  • CA_DIPLOMAT_EXEMPTION: This customer is exempt from specific taxes for holding a valid DIPLOMAT_EXEMPTION in Canada.
  • CA_BC_RESELLER_EXEMPTION: This customer is exempt from specific taxes for holding a valid RESELLER_EXEMPTION in British Columbia.
  • CA_MB_RESELLER_EXEMPTION: This customer is exempt from specific taxes for holding a valid RESELLER_EXEMPTION in Manitoba.
  • CA_SK_RESELLER_EXEMPTION: This customer is exempt from specific taxes for holding a valid RESELLER_EXEMPTION in Saskatchewan.
  • CA_BC_COMMERCIAL_FISHERY_EXEMPTION: This customer is exempt from specific taxes for holding a valid COMMERCIAL_FISHERY_EXEMPTION in British Columbia.
  • CA_MB_COMMERCIAL_FISHERY_EXEMPTION: This customer is exempt from specific taxes for holding a valid COMMERCIAL_FISHERY_EXEMPTION in Manitoba.
  • CA_NS_COMMERCIAL_FISHERY_EXEMPTION: This customer is exempt from specific taxes for holding a valid COMMERCIAL_FISHERY_EXEMPTION in Nova Scotia.
  • CA_PE_COMMERCIAL_FISHERY_EXEMPTION: This customer is exempt from specific taxes for holding a valid COMMERCIAL_FISHERY_EXEMPTION in Prince Edward Island.
  • CA_SK_COMMERCIAL_FISHERY_EXEMPTION: This customer is exempt from specific taxes for holding a valid COMMERCIAL_FISHERY_EXEMPTION in Saskatchewan.
  • CA_BC_PRODUCTION_AND_MACHINERY_EXEMPTION: This customer is exempt from specific taxes for holding a valid PRODUCTION_AND_MACHINERY_EXEMPTION in British Columbia.
  • CA_SK_PRODUCTION_AND_MACHINERY_EXEMPTION: This customer is exempt from specific taxes for holding a valid PRODUCTION_AND_MACHINERY_EXEMPTION in Saskatchewan.
  • CA_BC_SUB_CONTRACTOR_EXEMPTION: This customer is exempt from specific taxes for holding a valid SUB_CONTRACTOR_EXEMPTION in British Columbia.
  • CA_SK_SUB_CONTRACTOR_EXEMPTION: This customer is exempt from specific taxes for holding a valid SUB_CONTRACTOR_EXEMPTION in Saskatchewan.
  • CA_BC_CONTRACTOR_EXEMPTION: This customer is exempt from specific taxes for holding a valid CONTRACTOR_EXEMPTION in British Columbia.
  • CA_SK_CONTRACTOR_EXEMPTION: This customer is exempt from specific taxes for holding a valid CONTRACTOR_EXEMPTION in Saskatchewan.
  • CA_ON_PURCHASE_EXEMPTION: This customer is exempt from specific taxes for holding a valid PURCHASE_EXEMPTION in Ontario.
  • CA_MB_FARMER_EXEMPTION: This customer is exempt from specific taxes for holding a valid FARMER_EXEMPTION in Manitoba.
  • CA_NS_FARMER_EXEMPTION: This customer is exempt from specific taxes for holding a valid FARMER_EXEMPTION in Nova Scotia.
  • CA_SK_FARMER_EXEMPTION: This customer is exempt from specific taxes for holding a valid FARMER_EXEMPTION in Saskatchewan.
total_spent
read-only 
"total_spent": "375.30"

The total amount of money that the customer has spent across their order history.
updated_at
read-only 
"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
read-only 
"verified_email": true

Whether the customer has verified their email address.

Endpoints

GET /admin/api/2020-01/customers.json
Retrieves a list of customers. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
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)
fields

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

Retrieve all customers for a shop

GET /admin/api/2020-01/customers.json
View Response 
HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": false,
      "created_at": "2021-01-01T14:46:48-05:00",
      "updated_at": "2021-01-01T14:46:48-05:00",
      "first_name": "Bob",
      "last_name": "Norman",
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "199.65",
      "last_order_id": 450789469,
      "note": null,
      "verified_email": true,
      "multipass_identifier": null,
      "tax_exempt": false,
      "phone": "+16136120707",
      "tags": "",
      "last_order_name": "#1001",
      "currency": "USD",
      "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
        }
      ],
      "accepts_marketing_updated_at": "2005-06-12T11:57:11-04:00",
      "marketing_opt_in_level": null,
      "tax_exemptions": [],
      "admin_graphql_api_id": "gid://shopify/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 /admin/api/2020-01/customers.json?since_id=207119551
View Response 
HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": 1073339471,
      "email": "steve.lastnameson@example.com",
      "accepts_marketing": false,
      "created_at": "2021-01-01T14:47:22-05:00",
      "updated_at": "2021-01-01T14:47:23-05: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,
      "currency": "USD",
      "addresses": [
        {
          "id": 1053317307,
          "customer_id": 1073339471,
          "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
        }
      ],
      "accepts_marketing_updated_at": "2021-01-01T14:47:23-05:00",
      "marketing_opt_in_level": null,
      "tax_exemptions": [],
      "admin_graphql_api_id": "gid://shopify/Customer/1073339471",
      "default_address": {
        "id": 1053317307,
        "customer_id": 1073339471,
        "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 /admin/api/2020-01/customers.json?updated_at_min=2020-12-31 19:47:54
View Response 
HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": false,
      "created_at": "2021-01-01T14:47:29-05:00",
      "updated_at": "2021-01-01T14:47:29-05:00",
      "first_name": "Bob",
      "last_name": "Norman",
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "199.65",
      "last_order_id": 450789469,
      "note": null,
      "verified_email": true,
      "multipass_identifier": null,
      "tax_exempt": false,
      "phone": "+16136120707",
      "tags": "",
      "last_order_name": "#1001",
      "currency": "USD",
      "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
        }
      ],
      "accepts_marketing_updated_at": "2005-06-12T11:57:11-04:00",
      "marketing_opt_in_level": null,
      "tax_exemptions": [],
      "admin_graphql_api_id": "gid://shopify/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 /admin/api/2020-01/customers.json?ids=207119551,1073339472
View Response 
HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": 1073339472,
      "email": "steve.lastnameson@example.com",
      "accepts_marketing": false,
      "created_at": "2021-01-01T14:48:08-05:00",
      "updated_at": "2021-01-01T14:48:08-05: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,
      "currency": "USD",
      "addresses": [
        {
          "id": 1053317308,
          "customer_id": 1073339472,
          "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
        }
      ],
      "accepts_marketing_updated_at": "2021-01-01T14:48:08-05:00",
      "marketing_opt_in_level": null,
      "tax_exemptions": [],
      "admin_graphql_api_id": "gid://shopify/Customer/1073339472",
      "default_address": {
        "id": 1053317308,
        "customer_id": 1073339472,
        "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": "2021-01-01T14:47:55-05:00",
      "updated_at": "2021-01-01T14:47:55-05:00",
      "first_name": "Bob",
      "last_name": "Norman",
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "199.65",
      "last_order_id": 450789469,
      "note": null,
      "verified_email": true,
      "multipass_identifier": null,
      "tax_exempt": false,
      "phone": "+16136120707",
      "tags": "",
      "last_order_name": "#1001",
      "currency": "USD",
      "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
        }
      ],
      "accepts_marketing_updated_at": "2005-06-12T11:57:11-04:00",
      "marketing_opt_in_level": null,
      "tax_exemptions": [],
      "admin_graphql_api_id": "gid://shopify/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 /admin/api/2020-01/customers/search.json?query=Bob country:United States
Searches for customers that match a supplied query. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
order

Set the field and direction by which to order results.

(default: last_order_date DESC)
query

Text to search for in the shop's customer data. Note: Supported queries: accepts_marketing, activation_date, address1, address2, city, company, country, customer_date, customer_first_name, customer_id, customer_last_name, customer_tag, email, email_marketing_state, first_name, first_order_date, id, last_abandoned_order_date, last_name, multipass_identifier, orders_count, order_date, phone, province, shop_id, state, tag, total_spent, updated_at, verified_email, product_subscriber_status. All other queries returns all customers.

limit

The maximum number of results to show.

(default: 50, maximum: 250)
fields

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

Retrieve all customers with an address in the United States and the name "Bob"

GET /admin/api/2020-01/customers/search.json?query=Bob country:United States
View Response 
HTTP/1.1 200 OK
{
  "customers": [
    {
      "id": 207119551,
      "email": "bob.norman@hostmail.com",
      "accepts_marketing": false,
      "created_at": "2021-01-01T14:48:36-05:00",
      "updated_at": "2021-01-01T14:48:36-05:00",
      "first_name": "Bob",
      "last_name": "Norman",
      "orders_count": 1,
      "state": "disabled",
      "total_spent": "199.65",
      "last_order_id": 450789469,
      "note": null,
      "verified_email": true,
      "multipass_identifier": null,
      "tax_exempt": false,
      "phone": "+16136120707",
      "tags": "",
      "last_order_name": "#1001",
      "currency": "USD",
      "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
        }
      ],
      "accepts_marketing_updated_at": "2005-06-12T11:57:11-04:00",
      "marketing_opt_in_level": null,
      "tax_exemptions": [],
      "admin_graphql_api_id": "gid://shopify/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 /admin/api/2020-01/customers/{customer_id}.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 /admin/api/2020-01/customers/207119551.json
View Response 
HTTP/1.1 200 OK
{
  "customer": {
    "id": 207119551,
    "email": "bob.norman@hostmail.com",
    "accepts_marketing": false,
    "created_at": "2021-01-01T14:48:59-05:00",
    "updated_at": "2021-01-01T14:48:59-05:00",
    "first_name": "Bob",
    "last_name": "Norman",
    "orders_count": 1,
    "state": "disabled",
    "total_spent": "199.65",
    "last_order_id": 450789469,
    "note": null,
    "verified_email": true,
    "multipass_identifier": null,
    "tax_exempt": false,
    "phone": "+16136120707",
    "tags": "",
    "last_order_name": "#1001",
    "currency": "USD",
    "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
      }
    ],
    "accepts_marketing_updated_at": "2005-06-12T11:57:11-04:00",
    "marketing_opt_in_level": null,
    "tax_exemptions": [],
    "admin_graphql_api_id": "gid://shopify/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 /admin/api/2020-01/customers.json
Creates a customer.

Create a new customer record

POST /admin/api/2020-01/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"
      }
    ]
  }
}
View Response 
HTTP/1.1 201 Created
{
  "customer": {
    "id": 1073339473,
    "email": "steve.lastnameson@example.com",
    "accepts_marketing": false,
    "created_at": "2021-01-01T14:49:26-05:00",
    "updated_at": "2021-01-01T14:49:26-05: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,
    "currency": "USD",
    "addresses": [
      {
        "id": 1053317309,
        "customer_id": 1073339473,
        "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
      }
    ],
    "accepts_marketing_updated_at": "2021-01-01T14:49:26-05:00",
    "marketing_opt_in_level": null,
    "tax_exemptions": [],
    "admin_graphql_api_id": "gid://shopify/Customer/1073339473",
    "default_address": {
      "id": 1053317309,
      "customer_id": 1073339473,
      "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 /admin/api/2020-01/customers.json
{
  "customer": {
    "email": null,
    "first_name": null,
    "last_name": null
  }
}
View 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 /admin/api/2020-01/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"
      }
    ]
  }
}
View Response 
HTTP/1.1 201 Created
{
  "customer": {
    "id": 1073339474,
    "email": "steve.lastnameson@example.com",
    "accepts_marketing": false,
    "created_at": "2021-01-01T14:49:49-05:00",
    "updated_at": "2021-01-01T14:49:49-05: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,
    "currency": "USD",
    "addresses": [
      {
        "id": 1053317310,
        "customer_id": 1073339474,
        "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
      }
    ],
    "accepts_marketing_updated_at": "2021-01-01T14:49:49-05:00",
    "marketing_opt_in_level": null,
    "tax_exemptions": [],
    "admin_graphql_api_id": "gid://shopify/Customer/1073339474",
    "default_address": {
      "id": 1053317310,
      "customer_id": 1073339474,
      "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 /admin/api/2020-01/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
  }
}
View Response 
HTTP/1.1 201 Created
{
  "customer": {
    "id": 1073339475,
    "email": "steve.lastnameson@example.com",
    "accepts_marketing": false,
    "created_at": "2021-01-01T14:50:00-05:00",
    "updated_at": "2021-01-01T14:50:00-05: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,
    "currency": "USD",
    "addresses": [
      {
        "id": 1053317311,
        "customer_id": 1073339475,
        "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
      }
    ],
    "accepts_marketing_updated_at": "2021-01-01T14:50:00-05:00",
    "marketing_opt_in_level": null,
    "tax_exemptions": [],
    "admin_graphql_api_id": "gid://shopify/Customer/1073339475",
    "default_address": {
      "id": 1053317311,
      "customer_id": 1073339475,
      "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 /admin/api/2020-01/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
  }
}
View Response 
HTTP/1.1 201 Created
{
  "customer": {
    "id": 1073339476,
    "email": "steve.lastnameson@example.com",
    "accepts_marketing": false,
    "created_at": "2021-01-01T14:50:13-05:00",
    "updated_at": "2021-01-01T14:50:13-05: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,
    "currency": "USD",
    "addresses": [
      {
        "id": 1053317312,
        "customer_id": 1073339476,
        "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
      }
    ],
    "accepts_marketing_updated_at": "2021-01-01T14:50:13-05:00",
    "marketing_opt_in_level": null,
    "tax_exemptions": [],
    "admin_graphql_api_id": "gid://shopify/Customer/1073339476",
    "default_address": {
      "id": 1053317312,
      "customer_id": 1073339476,
      "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/api/2020-01/customers/{customer_id}.json
Updates a customer.

Update details for a customer

PUT /admin/api/2020-01/customers/207119551.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": "2021-01-01T14:50:13-05:00",
    "updated_at": "2021-01-01T14:50:27-05:00",
    "first_name": "Bob",
    "last_name": "Norman",
    "orders_count": 1,
    "state": "disabled",
    "total_spent": "199.65",
    "last_order_id": 450789469,
    "note": "Customer is a great guy",
    "verified_email": true,
    "multipass_identifier": null,
    "tax_exempt": false,
    "phone": "+16136120707",
    "tags": "",
    "last_order_name": "#1001",
    "currency": "USD",
    "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
      }
    ],
    "accepts_marketing_updated_at": "2021-01-01T14:50:27-05:00",
    "marketing_opt_in_level": null,
    "tax_exemptions": [],
    "admin_graphql_api_id": "gid://shopify/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 /admin/api/2020-01/customers/207119551.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": "2021-01-01T14:50:27-05:00",
    "updated_at": "2021-01-01T14:50:40-05:00",
    "first_name": "Bob",
    "last_name": "Norman",
    "orders_count": 1,
    "state": "disabled",
    "total_spent": "199.65",
    "last_order_id": 450789469,
    "note": null,
    "verified_email": true,
    "multipass_identifier": null,
    "tax_exempt": false,
    "phone": "+16136120707",
    "tags": "",
    "last_order_name": "#1001",
    "currency": "USD",
    "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
      }
    ],
    "accepts_marketing_updated_at": "2005-06-12T11:57:11-04:00",
    "marketing_opt_in_level": null,
    "tax_exemptions": [],
    "admin_graphql_api_id": "gid://shopify/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 /admin/api/2020-01/customers/207119551.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": "2021-01-01T14:50:41-05:00",
    "updated_at": "2021-01-01T14:50:53-05:00",
    "first_name": "Bob",
    "last_name": "Norman",
    "orders_count": 1,
    "state": "disabled",
    "total_spent": "199.65",
    "last_order_id": 450789469,
    "note": null,
    "verified_email": true,
    "multipass_identifier": null,
    "tax_exempt": false,
    "phone": "+16136120707",
    "tags": "New Customer, Repeat Customer",
    "last_order_name": "#1001",
    "currency": "USD",
    "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
      }
    ],
    "accepts_marketing_updated_at": "2005-06-12T11:57:11-04:00",
    "marketing_opt_in_level": null,
    "tax_exemptions": [],
    "admin_graphql_api_id": "gid://shopify/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 marketing opt-in state

PUT /admin/api/2020-01/customers/207119551.json
{
  "customer": {
    "id": 207119551,
    "accepts_marketing": true,
    "accepts_marketing_updated_at": "2020-12-29T14:51:05-05:00",
    "marketing_opt_in_level": "confirmed_opt_in"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "customer": {
    "id": 207119551,
    "email": "bob.norman@hostmail.com",
    "accepts_marketing": true,
    "created_at": "2021-01-01T14:50:53-05:00",
    "updated_at": "2021-01-01T14:51:05-05:00",
    "first_name": "Bob",
    "last_name": "Norman",
    "orders_count": 1,
    "state": "disabled",
    "total_spent": "199.65",
    "last_order_id": 450789469,
    "note": null,
    "verified_email": true,
    "multipass_identifier": null,
    "tax_exempt": false,
    "phone": "+16136120707",
    "tags": "",
    "last_order_name": "#1001",
    "currency": "USD",
    "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
      }
    ],
    "accepts_marketing_updated_at": "2020-12-29T14:51:05-05:00",
    "marketing_opt_in_level": "confirmed_opt_in",
    "tax_exemptions": [],
    "admin_graphql_api_id": "gid://shopify/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 /admin/api/2020-01/customers/{customer_id}/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 30 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 30 days, but the previous URL will no longer be valid.

Create an account activation URL for an invited or disabled customer

POST /admin/api/2020-01/customers/207119551/account_activation_url.json
{
}
View Response 
HTTP/1.1 200 OK
{
  "account_activation_url": "https://apple.myshopify.com/account/activate/207119551/2f1c39314b6c28b25a4c8658a0d75de3-1609530678"
}

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

POST /admin/api/2020-01/customers/207119551/account_activation_url.json
{
}
View Response 
HTTP/1.1 422 Unprocessable Entity
{
  "errors": [
    "account already enabled"
  ]
}
POST /admin/api/2020-01/customers/{customer_id}/send_invite.json
Sends an account invite to a customer.

Send the default invite

POST /admin/api/2020-01/customers/207119551/send_invite.json
{
  "customer_invite": {}
}
View 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 /admin/api/2020-01/customers/207119551/send_invite.json
{
  "customer_invite": {
    "to": "new_test_email@shopify.com",
    "from": "noaccesssteve@jobs.com",
    "bcc": [
      "noaccesssteve@jobs.com"
    ],
    "subject": "Welcome to my new shop",
    "custom_message": "My awesome new store"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "customer_invite": {
    "to": "new_test_email@shopify.com",
    "from": "noaccesssteve@jobs.com",
    "subject": "Welcome to my new shop",
    "custom_message": "My awesome new store",
    "bcc": [
      "noaccesssteve@jobs.com"
    ]
  }
}
DELETE /admin/api/2020-01/customers/{customer_id}.json
Deletes a customer. A customer can't be deleted if they have existing orders.

Remove an existing customer

DELETE /admin/api/2020-01/customers/207119551.json
View Response 
HTTP/1.1 422 Unprocessable Entity
{
  "errors": "Error deleting customer"
}
GET /admin/api/2020-01/customers/count.json
Retrieves a count of all customers.

Retrieve a count of all customers

GET /admin/api/2020-01/customers/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 1
}
GET /admin/api/2020-01/customers/{customer_id}/orders.json
Retrieves all orders belonging to a customer. The query string parameters that are available to the Order resource are also available to this endpoint.

Retrieve all orders from a customer

GET /admin/api/2020-01/customers/207119551/orders.json
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": "598.94",
      "subtotal_price": "597.00",
      "total_weight": 0,
      "total_tax": "11.94",
      "taxes_included": false,
      "currency": "USD",
      "financial_status": "partially_refunded",
      "confirmed": true,
      "total_discounts": "10.00",
      "total_line_items_price": "597.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": "598.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": "0.0.0.0",
      "client_details": {
        "accept_language": null,
        "browser_height": null,
        "browser_ip": "0.0.0.0",
        "browser_width": null,
        "session_hash": null,
        "user_agent": null
      },
      "landing_site_ref": "abc",
      "order_number": 1001,
      "discount_applications": [
        {
          "type": "discount_code",
          "value": "10.0",
          "value_type": "fixed_amount",
          "allocation_method": "across",
          "target_selection": "all",
          "target_type": "line_item",
          "code": "TENOFF"
        }
      ],
      "discount_codes": [
        {
          "code": "TENOFF",
          "amount": "10.00",
          "type": "fixed_amount"
        }
      ],
      "note_attributes": [
        {
          "name": "custom engraving",
          "value": "Happy Birthday"
        },
        {
          "name": "colour",
          "value": "green"
        }
      ],
      "payment_details": {
        "credit_card_bin": null,
        "avs_result_code": null,
        "cvv_result_code": null,
        "credit_card_number": "•••• •••• •••• 4242",
        "credit_card_company": "Visa",
        "credit_card_name": null,
        "credit_card_wallet": null,
        "credit_card_expiration_month": null,
        "credit_card_expiration_year": null
      },
      "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",
          "price_set": {
            "shop_money": {
              "amount": "11.94",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "11.94",
              "currency_code": "USD"
            }
          }
        }
      ],
      "tags": "",
      "contact_email": "bob.norman@hostmail.com",
      "order_status_url": "https://apple.myshopify.com/690933842/orders/b1946ac92492d2347c6235b4d2611184/authenticate?key=1bbd9982bbdd849d08ab19deca1a53de",
      "presentment_currency": "USD",
      "total_line_items_price_set": {
        "shop_money": {
          "amount": "597.00",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "597.00",
          "currency_code": "USD"
        }
      },
      "total_discounts_set": {
        "shop_money": {
          "amount": "10.00",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "10.00",
          "currency_code": "USD"
        }
      },
      "total_shipping_price_set": {
        "shop_money": {
          "amount": "0.00",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "0.00",
          "currency_code": "USD"
        }
      },
      "subtotal_price_set": {
        "shop_money": {
          "amount": "597.00",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "597.00",
          "currency_code": "USD"
        }
      },
      "total_price_set": {
        "shop_money": {
          "amount": "598.94",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "598.94",
          "currency_code": "USD"
        }
      },
      "total_tax_set": {
        "shop_money": {
          "amount": "11.94",
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": "11.94",
          "currency_code": "USD"
        }
      },
      "line_items": [
        {
          "id": 466157049,
          "variant_id": 39072856,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "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,
          "grams": 200,
          "price": "199.00",
          "total_discount": "0.00",
          "fulfillment_status": null,
          "price_set": {
            "shop_money": {
              "amount": "199.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "199.00",
              "currency_code": "USD"
            }
          },
          "total_discount_set": {
            "shop_money": {
              "amount": "0.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "0.00",
              "currency_code": "USD"
            }
          },
          "discount_allocations": [
            {
              "amount": "3.34",
              "discount_application_index": 0,
              "amount_set": {
                "shop_money": {
                  "amount": "3.34",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.34",
                  "currency_code": "USD"
                }
              }
            }
          ],
          "duties": [],
          "admin_graphql_api_id": "gid://shopify/LineItem/466157049",
          "tax_lines": [
            {
              "title": "State Tax",
              "price": "3.98",
              "rate": 0.06,
              "price_set": {
                "shop_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                }
              }
            }
          ]
        },
        {
          "id": 518995019,
          "variant_id": 49148385,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "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,
          "grams": 200,
          "price": "199.00",
          "total_discount": "0.00",
          "fulfillment_status": null,
          "price_set": {
            "shop_money": {
              "amount": "199.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "199.00",
              "currency_code": "USD"
            }
          },
          "total_discount_set": {
            "shop_money": {
              "amount": "0.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "0.00",
              "currency_code": "USD"
            }
          },
          "discount_allocations": [
            {
              "amount": "3.33",
              "discount_application_index": 0,
              "amount_set": {
                "shop_money": {
                  "amount": "3.33",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.33",
                  "currency_code": "USD"
                }
              }
            }
          ],
          "duties": [],
          "admin_graphql_api_id": "gid://shopify/LineItem/518995019",
          "tax_lines": [
            {
              "title": "State Tax",
              "price": "3.98",
              "rate": 0.06,
              "price_set": {
                "shop_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                }
              }
            }
          ]
        },
        {
          "id": 703073504,
          "variant_id": 457924702,
          "title": "IPod Nano - 8gb",
          "quantity": 1,
          "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,
          "grams": 200,
          "price": "199.00",
          "total_discount": "0.00",
          "fulfillment_status": null,
          "price_set": {
            "shop_money": {
              "amount": "199.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "199.00",
              "currency_code": "USD"
            }
          },
          "total_discount_set": {
            "shop_money": {
              "amount": "0.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "0.00",
              "currency_code": "USD"
            }
          },
          "discount_allocations": [
            {
              "amount": "3.33",
              "discount_application_index": 0,
              "amount_set": {
                "shop_money": {
                  "amount": "3.33",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.33",
                  "currency_code": "USD"
                }
              }
            }
          ],
          "duties": [],
          "admin_graphql_api_id": "gid://shopify/LineItem/703073504",
          "tax_lines": [
            {
              "title": "State Tax",
              "price": "3.98",
              "rate": 0.06,
              "price_set": {
                "shop_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                }
              }
            }
          ]
        }
      ],
      "fulfillments": [
        {
          "id": 255858046,
          "order_id": 450789469,
          "status": "failure",
          "created_at": "2021-01-01T14:52:23-05:00",
          "service": "manual",
          "updated_at": "2021-01-01T14:52:23-05:00",
          "tracking_company": "USPS",
          "shipment_status": null,
          "location_id": 905684977,
          "line_items": [
            {
              "id": 466157049,
              "variant_id": 39072856,
              "title": "IPod Nano - 8gb",
              "quantity": 1,
              "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,
              "grams": 200,
              "price": "199.00",
              "total_discount": "0.00",
              "fulfillment_status": null,
              "price_set": {
                "shop_money": {
                  "amount": "199.00",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "199.00",
                  "currency_code": "USD"
                }
              },
              "total_discount_set": {
                "shop_money": {
                  "amount": "0.00",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "0.00",
                  "currency_code": "USD"
                }
              },
              "discount_allocations": [
                {
                  "amount": "3.34",
                  "discount_application_index": 0,
                  "amount_set": {
                    "shop_money": {
                      "amount": "3.34",
                      "currency_code": "USD"
                    },
                    "presentment_money": {
                      "amount": "3.34",
                      "currency_code": "USD"
                    }
                  }
                }
              ],
              "duties": [],
              "admin_graphql_api_id": "gid://shopify/LineItem/466157049",
              "tax_lines": [
                {
                  "title": "State Tax",
                  "price": "3.98",
                  "rate": 0.06,
                  "price_set": {
                    "shop_money": {
                      "amount": "3.98",
                      "currency_code": "USD"
                    },
                    "presentment_money": {
                      "amount": "3.98",
                      "currency_code": "USD"
                    }
                  }
                }
              ]
            }
          ],
          "tracking_number": "1Z2345",
          "tracking_numbers": [
            "1Z2345"
          ],
          "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?qtc_tLabels1=1Z2345",
          "tracking_urls": [
            "https://tools.usps.com/go/TrackConfirmAction_input?qtc_tLabels1=1Z2345"
          ],
          "receipt": {
            "testcase": true,
            "authorization": "123456"
          },
          "name": "#1001.0",
          "admin_graphql_api_id": "gid://shopify/Fulfillment/255858046"
        }
      ],
      "refunds": [
        {
          "id": 509562969,
          "order_id": 450789469,
          "created_at": "2021-01-01T14:52:23-05:00",
          "note": "it broke during shipping",
          "user_id": 799407056,
          "processed_at": "2021-01-01T14:52:23-05:00",
          "restock": true,
          "duties": [],
          "total_duties_set": {
            "shop_money": {
              "amount": "0.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "0.00",
              "currency_code": "USD"
            }
          },
          "admin_graphql_api_id": "gid://shopify/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,
              "subtotal_set": {
                "shop_money": {
                  "amount": "195.67",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "195.67",
                  "currency_code": "USD"
                }
              },
              "total_tax_set": {
                "shop_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                }
              },
              "line_item": {
                "id": 703073504,
                "variant_id": 457924702,
                "title": "IPod Nano - 8gb",
                "quantity": 1,
                "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,
                "grams": 200,
                "price": "199.00",
                "total_discount": "0.00",
                "fulfillment_status": null,
                "price_set": {
                  "shop_money": {
                    "amount": "199.00",
                    "currency_code": "USD"
                  },
                  "presentment_money": {
                    "amount": "199.00",
                    "currency_code": "USD"
                  }
                },
                "total_discount_set": {
                  "shop_money": {
                    "amount": "0.00",
                    "currency_code": "USD"
                  },
                  "presentment_money": {
                    "amount": "0.00",
                    "currency_code": "USD"
                  }
                },
                "discount_allocations": [
                  {
                    "amount": "3.33",
                    "discount_application_index": 0,
                    "amount_set": {
                      "shop_money": {
                        "amount": "3.33",
                        "currency_code": "USD"
                      },
                      "presentment_money": {
                        "amount": "3.33",
                        "currency_code": "USD"
                      }
                    }
                  }
                ],
                "duties": [],
                "admin_graphql_api_id": "gid://shopify/LineItem/703073504",
                "tax_lines": [
                  {
                    "title": "State Tax",
                    "price": "3.98",
                    "rate": 0.06,
                    "price_set": {
                      "shop_money": {
                        "amount": "3.98",
                        "currency_code": "USD"
                      },
                      "presentment_money": {
                        "amount": "3.98",
                        "currency_code": "USD"
                      }
                    }
                  }
                ]
              }
            },
            {
              "id": 709875399,
              "quantity": 1,
              "line_item_id": 466157049,
              "location_id": 487838322,
              "restock_type": "legacy_restock",
              "subtotal": 195.66,
              "total_tax": 3.98,
              "subtotal_set": {
                "shop_money": {
                  "amount": "195.66",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "195.66",
                  "currency_code": "USD"
                }
              },
              "total_tax_set": {
                "shop_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                },
                "presentment_money": {
                  "amount": "3.98",
                  "currency_code": "USD"
                }
              },
              "line_item": {
                "id": 466157049,
                "variant_id": 39072856,
                "title": "IPod Nano - 8gb",
                "quantity": 1,
                "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,
                "grams": 200,
                "price": "199.00",
                "total_discount": "0.00",
                "fulfillment_status": null,
                "price_set": {
                  "shop_money": {
                    "amount": "199.00",
                    "currency_code": "USD"
                  },
                  "presentment_money": {
                    "amount": "199.00",
                    "currency_code": "USD"
                  }
                },
                "total_discount_set": {
                  "shop_money": {
                    "amount": "0.00",
                    "currency_code": "USD"
                  },
                  "presentment_money": {
                    "amount": "0.00",
                    "currency_code": "USD"
                  }
                },
                "discount_allocations": [
                  {
                    "amount": "3.34",
                    "discount_application_index": 0,
                    "amount_set": {
                      "shop_money": {
                        "amount": "3.34",
                        "currency_code": "USD"
                      },
                      "presentment_money": {
                        "amount": "3.34",
                        "currency_code": "USD"
                      }
                    }
                  }
                ],
                "duties": [],
                "admin_graphql_api_id": "gid://shopify/LineItem/466157049",
                "tax_lines": [
                  {
                    "title": "State Tax",
                    "price": "3.98",
                    "rate": 0.06,
                    "price_set": {
                      "shop_money": {
                        "amount": "3.98",
                        "currency_code": "USD"
                      },
                      "presentment_money": {
                        "amount": "3.98",
                        "currency_code": "USD"
                      }
                    }
                  }
                ]
              }
            }
          ],
          "transactions": [
            {
              "id": 179259969,
              "order_id": 450789469,
              "kind": "refund",
              "gateway": "bogus",
              "status": "success",
              "message": null,
              "created_at": "2005-08-05T12:59:12-04:00",
              "test": false,
              "authorization": "authorization-key",
              "location_id": null,
              "user_id": null,
              "parent_id": 801038806,
              "processed_at": "2005-08-05T12:59:12-04:00",
              "device_id": null,
              "error_code": null,
              "source_name": "web",
              "receipt": {},
              "amount": "209.00",
              "currency": "USD",
              "admin_graphql_api_id": "gid://shopify/OrderTransaction/179259969"
            }
          ],
          "order_adjustments": []
        }
      ],
      "total_tip_received": "0.0",
      "original_total_duties_set": null,
      "current_total_duties_set": null,
      "admin_graphql_api_id": "gid://shopify/Order/450789469",
      "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,
          "discounted_price": "0.00",
          "price_set": {
            "shop_money": {
              "amount": "0.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "0.00",
              "currency_code": "USD"
            }
          },
          "discounted_price_set": {
            "shop_money": {
              "amount": "0.00",
              "currency_code": "USD"
            },
            "presentment_money": {
              "amount": "0.00",
              "currency_code": "USD"
            }
          },
          "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"
      },
      "customer": {
        "id": 207119551,
        "email": "bob.norman@hostmail.com",
        "accepts_marketing": false,
        "created_at": "2021-01-01T14:52:23-05:00",
        "updated_at": "2021-01-01T14:52:23-05:00",
        "first_name": "Bob",
        "last_name": "Norman",
        "orders_count": 1,
        "state": "disabled",
        "total_spent": "199.65",
        "last_order_id": 450789469,
        "note": null,
        "verified_email": true,
        "multipass_identifier": null,
        "tax_exempt": false,
        "phone": "+16136120707",
        "tags": "",
        "last_order_name": "#1001",
        "currency": "USD",
        "accepts_marketing_updated_at": "2005-06-12T11:57:11-04:00",
        "marketing_opt_in_level": null,
        "tax_exemptions": [],
        "admin_graphql_api_id": "gid://shopify/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
        }
      }
    }
  ]
}
Version 2020-04

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 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

Whether the customer has consented to receive marketing material via email.
accepts_marketing_updated_at 
"accepts_marketing_updated_at": "2013-06-27T08:48:27-04:00"

The date and time (ISO 8601 format) when the customer consented or objected to receiving marketing material by email. Set this value whenever the customer consents or objects to marketing materials.
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 code for the region of the address, such as the province, state, or district. For example QC for Quebec, Canada.
  • zip: The customer's postal code, also known as zip, postcode, Eircode, etc.
currency
read-only 
"currency": "JPY"

The three-letter code (ISO 4217 format) for the currency that the customer used when they paid for their last order. Defaults to the shop currency. Returns the shop currency for test orders.

created_at
read-only 
"created_at": "2013-06-27T08:48:27-04:00"

The date and time (ISO 8601 format) when the customer was created.
default_address
read-only 
"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
read-only 
"last_order_id": 234132602919

The ID of the customer's last order.
last_order_name
read-only 
"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.
marketing_opt_in_level
read-only 
"marketing_opt_in_level": "single_opt_in"

The marketing subscription opt-in level (as described by the M3AAWG best practices guideline) that the customer gave when they consented to receive marketing material by email. If the customer does not accept email marketing, then this property will be set to null. Valid values:

  • single_opt_in
  • confirmed_opt_in
  • unknown
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
read-only 
"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
read-only 
"state": "disabled"

The state of the customer's account with a shop. Default value: disabled. Valid values:

  • disabled: The customer doesn't have an active account. Customer accounts can be disabled from the Shopify admin at any time.
  • invited: The customer has received an email 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. A customer can have up to 250 tags. Each tag can have up to 255 characters.
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.
tax_exemptions 
"tax_exemptions": [
  "CA_STATUS_CARD_EXEMPTION",
  "CA_BC_RESELLER_EXEMPTION"
]

Whether the customer is exempt from paying specific taxes on their order. Canadian taxes only. Valid values:

  • EXEMPT_ALL: This customer is exempt from all Canadian taxes.
  • CA_STATUS_CARD_EXEMPTION: This customer is exempt from specific taxes for holding a valid STATUS_CARD_EXEMPTION in Canada.
  • CA_DIPLOMAT_EXEMPTION: This customer is exempt from specific taxes for holding a valid DIPLOMAT_EXEMPTION in Canada.
  • CA_BC_RESELLER_EXEMPTION: This customer is exempt from specific taxes for holding a valid RESELLER_EXEMPTION in British Columbia.
  • CA_MB_RESELLER_EXEMPTION: This customer is exempt from specific taxes for holding a valid RESELLER_EXEMPTION in Manitoba.
  • CA_SK_RESELLER_EXEMPTION: This customer is exempt from specific taxes for holding a valid RESELLER_EXEMPTION in Saskatchewan.
  • CA_BC_COMMERCIAL_FISHERY_EXEMPTION: This customer is exempt from specific taxes for holding a valid COMMERCIAL_FISHERY_EXEMPTION in British Columbia.
  • CA_MB_COMMERCIAL_FISHERY_EXEMPTION: This customer is exempt from specific taxes for holding a valid COMMERCIAL_FISHERY_EXEMPTION in Manitoba.
  • CA_NS_COMMERCIAL_FISHERY_EXEMPTION: This customer is exempt from specific taxes for holding a valid COMMERCIAL_FISHERY_EXEMPTION in Nova Scotia.
  • CA_PE_COMMERCIAL_FISHERY_EXEMPTION: This customer is exempt from specific taxes for holding a valid COMMERCIAL_FISHERY_EXEMPTION in Prince Edward Island.
  • CA_SK_COMMERCIAL_FISHERY_EXEMPTION: This customer is exempt from specific taxes for holding a valid COMMERCIAL_FISHERY_EXEMPTION in Saskatchewan.
  • CA_BC_PRODUCTION_AND_MACHINERY_EXEMPTION: This customer is exempt from specific taxes for holding a valid PRODUCTION_AND_MACHINERY_EXEMPTION in British Columbia.
  • CA_SK_PRODUCTION_AND_MACHINERY_EXEMPTION: This customer is exempt from specific taxes for holding a valid PRODUCTION_AND_MACHINERY_EXEMPTION in Saskatchewan.
  • CA_BC_SUB_CONTRACTOR_EXEMPTION: This customer is exempt from specific taxes for holding a valid SUB_CONTRACTOR_EXEMPTION in British Columbia.
  • CA_SK_SUB_CONTRACTOR_EXEMPTION: This customer is exempt from specific taxes for holding a valid SUB_CONTRACTOR_EXEMPTION in Saskatchewan.
  • CA_BC_CONTRACTOR_EXEMPTION: This customer is exempt from specific taxes for holding a valid CONTRACTOR_EXEMPTION in British Columbia.
  • CA_SK_CONTRACTOR_EXEMPTION: This customer is exempt from specific taxes for holding a valid CONTRACTOR_EXEMPTION in Saskatchewan.
  • CA_ON_PURCHASE_EXEMPTION: This customer is exempt from specific taxes for holding a valid PURCHASE_EXEMPTION in Ontario.
  • CA_MB_FARMER_EXEMPTION: This customer is exempt from specific taxes for holding a valid FARMER_EXEMPTION in Manitoba.
  • CA_NS_FARMER_EXEMPTION: This customer is exempt from specific taxes for holding a valid FARMER_EXEMPTION in Nova Scotia.
  • CA_SK_FARMER_EXEMPTION: This customer is exempt from specific taxes for holding a valid FARMER_EXEMPTION in Saskatchewan.
total_spent
read-only 
"total_spent": "375.30"

The total amount of money that the customer has spent across their order history.
updated_at
read-only 
"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
read-only 
"verified_email": true

Whether the customer has verified their email address.

Endpoints

GET /admin/api/2020-04/customers.json
Retrieves a list of customers. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
ids