Customer
The Customer resource stores information about a shop's customers, such as their contact details, their order history, and whether they've agreed to receive email marketing.

The Customer resource also holds information on the status of a customer's account. Customers with accounts save time at checkout when they're logged in because they don't need to enter their contact information. You can use the Customer API to check whether a customer has an active account, and then invite them to create one if they don't.
For security reasons, the Customer resource doesn't store credit card information. Customers always need to enter this information at checkout.
In a shop's checkout settings, there are three options for customer accounts:
- Accounts are disabled: Customers can't create accounts and can check out only as guests.
- Accounts are optional: Customers have the choice of either signing into their account or checking out as a guest. Customers can create accounts for themselves, and the shop owner can create an account for a customer and then invite them by email to use it.
- Accounts are required: Customers can't check out unless they're logged in, and the shop owner must create their accounts.
What you can do with Customer
The Shopify API lets you do the following with the Customer resource. More detailed versions of these general actions may be available:
- GET /admin/api/2020-01/customers.json Retrieves a list of customers
- GET /admin/api/2020-01/customers/search.json?query=Bob country:United States Searches for customers that match a supplied query
- GET /admin/api/2020-01/customers/{customer_id}.json Retrieves a single customer
- POST /admin/api/2020-01/customers.json Creates a customer
- PUT /admin/api/2020-01/customers/{customer_id}.json Updates a customer
- POST /admin/api/2020-01/customers/{customer_id}/account_activation_url.json Creates an account activation URL for a customer
- POST /admin/api/2020-01/customers/{customer_id}/send_invite.json Sends an account invite to a customer
- DELETE /admin/api/2020-01/customers/{customer_id}.json Deletes a customer.
- GET /admin/api/2020-01/customers/count.json Retrieves a count of customers
- GET /admin/api/2020-01/customers/{customer_id}/orders.json Retrieves all orders belonging to a customer
Customer properties
accepts_marketing |
Whether the customer has consented to receive marketing material via email. |
accepts_marketing_updated_at |
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 |
A list of the ten most recently updated addresses for the customer. Each address has the following properties:
|
currency
read-only |
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 |
The date and time (ISO 8601 format) when the customer was created. |
default_address
read-only |
The default address for the customer. The default address has the following properties:
|
The unique email address of the customer. Attempting to assign the same email address to multiple customers returns an error. |
|
first_name |
The customer's first name. |
id |
A unique identifier for the customer. |
last_name |
The customer's last name. |
last_order_id
read-only |
The ID of the customer's last order. |
last_order_name
read-only |
The name of the customer's last order. This is directly related to the |
metafield |
Attaches additional metadata to a shop's resources:
|
marketing_opt_in_level
read-only |
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
|
multipass_identifier |
A unique identifier for the customer that's used with ' 'Multipass login. |
note |
A note about the customer. |
orders_count
read-only |
The number of orders associated with this customer. |
phone |
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:
|
state
read-only |
The state of the customer's account with a shop. Default value:
|
tags |
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 |
Whether the customer is exempt from paying taxes on their order. If |
tax_exemptions |
Whether the customer is exempt from paying specific taxes on their order. Canadian taxes only. Valid values:
|
total_spent
read-only |
The total amount of money that the customer has spent across their order history. |
updated_at
read-only |
The date and time (ISO 8601 format) when the customer information was last updated. |
verified_email
read-only |
Whether the customer has verified their email address. |
Endpoints
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. |
created_at_max
|
Show customers created before a specified date. |
updated_at_min
|
Show customers last updated after a specified date. |
updated_at_max
|
Show customers last updated before a specified date. |
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
}
}
]
}
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: |
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
}
}
]
}
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
}
}
}
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
}
}
}
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
}
}
}
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
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
HTTP/1.1 422 Unprocessable Entity
{
"errors": [
"account already enabled"
]
}
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"
]
}
}
Remove an existing customer
DELETE /admin/api/2020-01/customers/207119551.json
View Response
HTTP/1.1 422 Unprocessable Entity
{
"errors": "Error deleting customer"
}
Retrieve a count of all customers
GET /admin/api/2020-01/customers/count.json
View Response
HTTP/1.1 200 OK
{
"count": 1
}
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
}
}
}
]
}
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:
- GET /admin/api/2020-04/customers.json Retrieves a list of customers
- GET /admin/api/2020-04/customers/search.json?query=Bob country:United States Searches for customers that match a supplied query
- GET /admin/api/2020-04/customers/{customer_id}.json Retrieves a single customer
- POST /admin/api/2020-04/customers.json Creates a customer
- PUT /admin/api/2020-04/customers/{customer_id}.json Updates a customer
- POST /admin/api/2020-04/customers/{customer_id}/account_activation_url.json Creates an account activation URL for a customer
- POST /admin/api/2020-04/customers/{customer_id}/send_invite.json Sends an account invite to a customer
- DELETE /admin/api/2020-04/customers/{customer_id}.json Deletes a customer.
- GET /admin/api/2020-04/customers/count.json Retrieves a count of customers
- GET /admin/api/2020-04/customers/{customer_id}/orders.json Retrieves all orders belonging to a customer
Customer properties
accepts_marketing |
Whether the customer has consented to receive marketing material via email. |
accepts_marketing_updated_at |
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 |
A list of the ten most recently updated addresses for the customer. Each address has the following properties:
|
currency
read-only |
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 |
The date and time (ISO 8601 format) when the customer was created. |
default_address
read-only |
The default address for the customer. The default address has the following properties:
|
The unique email address of the customer. Attempting to assign the same email address to multiple customers returns an error. |
|
first_name |
The customer's first name. |
id |
A unique identifier for the customer. |
last_name |
The customer's last name. |
last_order_id
read-only |
The ID of the customer's last order. |
last_order_name
read-only |
The name of the customer's last order. This is directly related to the |
metafield |
Attaches additional metadata to a shop's resources:
|
marketing_opt_in_level
read-only |
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
|
multipass_identifier |
A unique identifier for the customer that's used with ' 'Multipass login. |
note |
A note about the customer. |
orders_count
read-only |
The number of orders associated with this customer. |
phone |
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:
|
state
read-only |
The state of the customer's account with a shop. Default value:
|
tags |
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 |
Whether the customer is exempt from paying taxes on their order. If |
tax_exemptions |
Whether the customer is exempt from paying specific taxes on their order. Canadian taxes only. Valid values:
|
total_spent
read-only |
The total amount of money that the customer has spent across their order history. |
updated_at
read-only |
The date and time (ISO 8601 format) when the customer information was last updated. |
verified_email
read-only |
Whether the customer has verified their email address. |
Endpoints
page
parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
ids
|