Skip to main content

The REST Admin API is a legacy API as of October 1, 2024. Starting April 1, 2025, all new public apps must be built exclusively with the GraphQL Admin API. For details and migration steps, visit our migration guide.

Customer

Multiple access scopes needed — refer to each endpoint for access scope requirements.
Requires access to protected customer data.

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.

Caution: Only use this data if it is necessary for the intended app functionality. Shopify retains the ability to restrict access to API Access scopes for apps not requiring legitimate use of the associated data.

Was this section helpful?
#

Endpoints

Anchor to

The Customer resource

Anchor to

Properties

addresses
->
addresses

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

Show addresses 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
deprecated

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

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

default_address
read-only
->
defaultAddress

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

Show default_address 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 alphanumeric code for the customer's region.
  • zip: The customer's postal code, also known as zip, postcode, Eircode, etc.
email
->
email

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

email_marketing_consent
->
emailMarketingConsent

The marketing consent information when the customer consented to receiving marketing material by email. The email property is required to create a customer with email consent information and to update a customer for email consent that doesn't have an email recorded. The customer must have a unique email address associated to the record. The email marketing consent has the following properties:

Show email_marketing_consent properties
  • state: The current email marketing state for the customer.
  • opt_in_level: The marketing subscription opt-in level, as described in the M3AAWG Sender Best Common Practices, that the customer gave when they consented to receive marketing material by email.
  • consent_updated_at: The date and time when the customer consented to receive marketing material by email. If no date is provided, then the date and time when the consent information was sent is used.
first_name
->
firstName

The customer's first name.

id
->
id

A unique identifier for the customer.

last_name
->
lastName

The customer's last name.

last_order_id
read-only
->
lastOrder

The ID of the customer's last order.

last_order_name
read-only
->
lastOrder

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

metafield
->
metafield

Attaches additional metadata to a shop's resources:

Show metafield properties
  • 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.
  • type (required): The type. Refer to the full list of types.
  • description (optional): Additional information about the metafield.
Was this section helpful?
{}

The Customer resource

{
"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
}
],
"currency": "JPY",
"created_at": "2013-06-27T08:48:27-04:00",
"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
},
"email": "bob.norman@mail.example.com",
"email_marketing_consent": {
"state": "subscribed",
"opt_in_level": "confirmed_opt_in",
"consent_updated_at": "2022-04-01T11:22:06-04:00"
},
"first_name": "John",
"id": 207119551,
"last_name": "Norman",
"last_order_id": 234132602919,
"last_order_name": "#1169",
"metafield": {
"key": "new",
"namespace": "global",
"value": "newvalue",
"type": "string"
},
"marketing_opt_in_level": "confirmed_opt_in",
"multipass_identifier": null,
"note": "Placed an order that had a fraud warning",
"orders_count": 3,
"password": "password",
"password_confirmation": "password_confirmation",
"phone": "+16135551111",
"sms_marketing_consent": {
"state": "subscribed",
"opt_in_level": "single_opt_in",
"consent_updated_at": "2021-08-03T15:31:06-04:00",
"consent_collected_from": "OTHER"
},
"state": "disabled",
"tags": "loyal",
"tax_exempt": true,
"tax_exemptions": [
"CA_STATUS_CARD_EXEMPTION",
"CA_BC_RESELLER_EXEMPTION"
],
"total_spent": "375.30",
"updated_at": "2012-08-24T14:01:46-04:00",
"verified_email": true
}

Anchor to POST request, Creates a customer
post
Creates a customer

customerCreate
Requires customers access scope.

Creates a customer.

Anchor to Parameters of Creates a customerParameters

api_version
string
required
Was this section helpful?

Anchor to post-customers-examplesExamples

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

Request body
customer
Customer resource
Show customer properties
customer.first_name:"Steve"
->
firstName

The customer's first name.

customer.last_name:"Lastnameson"
->
lastName

The customer's last name.

customer.email:"steve.lastnameson@example.com"
->
email

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

customer.phone:"+15142546011"
->
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:

Show phone properties
  • 6135551212
  • +16135551212
  • (613)555-1212
  • +1 613-555-1212
customer.verified_email:true
read-only

Whether the customer has verified their email address.

customer.addresses:[{"address1":"123 Oak St","city":"Ottawa","province":"ON","phone":"555-1212","zip":"123 ABC","last_name":"Lastnameson","first_name":"Mother","country":"CA"}]

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

Show addresses 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.
customer.password:"newpass"
deprecated

The customer's password.

customer.password_confirmation:"newpass"
deprecated

The customer's password that's confirmed.

Create a customer with send_email_invite

Request body
customer
Customer resource
Show customer properties
customer.first_name:"Steve"
->
firstName

The customer's first name.

customer.last_name:"Lastnameson"
->
lastName

The customer's last name.

customer.email:"steve.lastnameson@example.com"
->
email

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

customer.phone:"+15142546011"
->
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:

Show phone properties
  • 6135551212
  • +16135551212
  • (613)555-1212
  • +1 613-555-1212
customer.verified_email:true
read-only

Whether the customer has verified their email address.

customer.addresses:[{"address1":"123 Oak St","city":"Ottawa","province":"ON","phone":"555-1212","zip":"123 ABC","last_name":"Lastnameson","first_name":"Mother","country":"CA"}]

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

Show addresses 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.

Create a customer with a metafield

Request body
customer
Customer resource
Show customer properties
customer.first_name:"Steve"
->
firstName

The customer's first name.

customer.last_name:"Lastnameson"
->
lastName

The customer's last name.

customer.email:"steve.lastnameson@example.com"
->
email

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

customer.phone:"+15142546011"
->
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:

Show phone properties
  • 6135551212
  • +16135551212
  • (613)555-1212
  • +1 613-555-1212
customer.verified_email:true
read-only

Whether the customer has verified their email address.

customer.addresses:[{"address1":"123 Oak St","city":"Ottawa","province":"ON","phone":"555-1212","zip":"123 ABC","last_name":"Lastnameson","first_name":"Mother","country":"CA"}]

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

Show addresses 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.

Create a new customer record

Request body
customer
Customer resource
Show customer properties
customer.first_name:"Steve"
->
firstName

The customer's first name.

customer.last_name:"Lastnameson"
->
lastName

The customer's last name.

customer.email:"steve.lastnameson@example.com"
->
email

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

customer.phone:"+15142546011"
->
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:

Show phone properties
  • 6135551212
  • +16135551212
  • (613)555-1212
  • +1 613-555-1212
customer.verified_email:true
read-only

Whether the customer has verified their email address.

customer.addresses:[{"address1":"123 Oak St","city":"Ottawa","province":"ON","phone":"555-1212","zip":"123 ABC","last_name":"Lastnameson","first_name":"Mother","country":"CA"}]

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

Show addresses 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.

Creating a customer with a phone number that belongs to an existing customer returns an error

Request body
customer
Customer resource
Show customer properties
customer.phone:"+16136120707"
->
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:

Show phone properties
  • 6135551212
  • +16135551212
  • (613)555-1212
  • +1 613-555-1212
customer.first_name:"Tobi"
->
firstName

The customer's first name.

customer.last_name:"Lutke"
->
lastName

The customer's last name.

Creating a customer with an email that belongs to an existing customer returns an error

Request body
customer
Customer resource
Show customer properties
customer.email:"bob.norman@mail.example.com"
->
email

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

customer.first_name:"Tobi"
->
firstName

The customer's first name.

customer.last_name:"Lutke"
->
lastName

The customer's last name.

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

Request body
customer
Customer resource
Show customer properties
customer.email:null
->
email

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

customer.first_name:null
->
firstName

The customer's first name.

customer.last_name:null
->
lastName

The customer's last name.

Was this section helpful?
post

/admin/api/2025-07/customers.json

curl -d '{"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}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2025-07/customers.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"

{}

Response

JSON
HTTP/1.1 201 Created
{
"customer": {
"email": "steve.lastnameson@example.com",
"first_name": "Steve",
"last_name": "Lastnameson",
"id": 1073339470,
"updated_at": "2025-07-01T14:37:24-04:00",
"created_at": "2025-07-01T14:37:23-04:00",
"orders_count": 0,
"state": "enabled",
"total_spent": "0.00",
"last_order_id": null,
"note": null,
"verified_email": true,
"multipass_identifier": null,
"tax_exempt": false,
"tags": "",
"last_order_name": null,
"currency": "USD",
"phone": "+15142546011",
"addresses": [
{
"id": 1053317300,
"customer_id": 1073339470,
"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
}
],
"tax_exemptions": [],
"email_marketing_consent": {
"state": "not_subscribed",
"opt_in_level": "single_opt_in",
"consent_updated_at": null
},
"sms_marketing_consent": {
"state": "not_subscribed",
"opt_in_level": "single_opt_in",
"consent_updated_at": null,
"consent_collected_from": "OTHER"
},
"admin_graphql_api_id": "gid://shopify/Customer/1073339470",
"default_address": {
"id": 1053317300,
"customer_id": 1073339470,
"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": false
}
}
}

Anchor to POST request, Creates an account activation URL for a customer
post
Creates an account activation URL for a customer

customerGenerateAccountActivationUrl
Requires customers access scope.

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.

Anchor to Parameters of Creates an account activation URL for a customerParameters

api_version
string
required
customer_id
string
required
Was this section helpful?

Anchor to post-customers-customer-id-account-activation-url-examplesExamples

Create an account activation URL for an invited or disabled customer

Path parameters
customer_id=207119551
string
required

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

Path parameters
customer_id=207119551
string
required
Was this section helpful?
post

/admin/api/2025-07/customers/207119551/account_activation_url.json

curl -d '{}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2025-07/customers/207119551/account_activation_url.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"

{}

Response

JSON
HTTP/1.1 200 OK
{
"account_activation_url": "https://jsmith.myshopify.com/account/activate/207119551/5fb848100b352ca81ee88f58094c9977-1751394901"
}

Anchor to POST request, Sends an account invite to a customer
post
Sends an account invite to a customer

customerSendAccountInviteEmail
Requires customers access scope.

Sends an account invite to a customer.

Anchor to Parameters of Sends an account invite to a customerParameters

api_version
string
required
customer_id
string
required
Was this section helpful?

Anchor to post-customers-customer-id-send-invite-examplesExamples

Send a customized invite

Path parameters
customer_id=207119551
string
required

Send the default invite

Path parameters
customer_id=207119551
string
required
Was this section helpful?
post

/admin/api/2025-07/customers/207119551/send_invite.json

curl -d '{"customer_invite":{"to":"new_test_email@shopify.com","from":"j.limited@example.com","bcc":["j.limited@example.com"],"subject":"Welcome to my new shop","custom_message":"My awesome new store"}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2025-07/customers/207119551/send_invite.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"

{}

Response

JSON
HTTP/1.1 201 Created
{
"customer_invite": {
"to": "new_test_email@shopify.com",
"from": "j.limited@example.com",
"subject": "Welcome to my new shop",
"custom_message": "My awesome new store",
"bcc": [
"j.limited@example.com"
]
}
}

Anchor to GET request, Retrieves a list of customers
get
Retrieves a list of customers

customers
Requires customers access scope.

Retrieves a list of customers. Note: This endpoint implements pagination by using links that are provided in the response header. To learn more, refer to Make paginated requests to the REST Admin API.

Anchor to Parameters of Retrieves a list of customersParameters

api_version
string
required
created_at_max

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

created_at_min

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

fields

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

ids

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

limit
≤ 250
default 50

The maximum number of results to show.

since_id

Restrict results to those after the specified ID.

updated_at_max

Show customers last updated 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)

Was this section helpful?

Anchor to get-customers?ids=207119551,562393516,1073339464-examplesExamples

Retrieve a list of specific customers

Query parameters
ids=207119551,562393516,1073339464

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

Retrieve all customers after a specified ID

Query parameters
since_id=207119551

Restrict results to those after the specified ID.

Retrieve all customers changed after a certain date

Query parameters
updated_at_min=2025-06-30+18:35:09

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

Retrieve all customers for a shop

Retrieve only the specified customer fields

Query parameters
fields=id,email,tags

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

Was this section helpful?
get

/admin/api/2025-07/customers.json?ids=207119551,562393516,1073339464

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/customers.json?ids=207119551%2C562393516%2C1073339464" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"customers": [
{
"id": 1073339464,
"email": "steve.lastnameson@example.com",
"created_at": "2025-07-01T14:34:25-04:00",
"updated_at": "2025-07-01T14:34:25-04:00",
"first_name": "Steve",
"last_name": "Lastnameson",
"orders_count": 0,
"state": "disabled",
"total_spent": "0.00",
"last_order_id": null,
"note": null,
"verified_email": true,
"multipass_identifier": null,
"tax_exempt": false,
"tags": "",
"last_order_name": null,
"currency": "USD",
"phone": "+15142546011",
"addresses": [
{
"id": 1053317295,
"customer_id": 1073339464,
"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",

Anchor to GET request, Retrieves a single customer
get
Retrieves a single customer

customer
Requires customers access scope.

Retrieves a single customer.

Anchor to Parameters of Retrieves a single customerParameters

api_version
string
required
customer_id
string
required
fields

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

Was this section helpful?

Anchor to get-customers-customer-id-examplesExamples

Retrieve a single customer by their ID

Path parameters
customer_id=207119551
string
required
Was this section helpful?
get

/admin/api/2025-07/customers/207119551.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/customers/207119551.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"customer": {
"id": 207119551,
"email": "bob.norman@mail.example.com",
"created_at": "2025-07-01T14:33:13-04:00",
"updated_at": "2025-07-01T14:33:13-04: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,
"tags": "Léon, Noël",
"last_order_name": "#1001",
"currency": "USD",
"phone": "+16136120707",
"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
}
],
"tax_exemptions": [],
"email_marketing_consent": {
"state": "not_subscribed",
"opt_in_level": null,
"consent_updated_at": "2004-06-13T11:57:11-04:00"
},
"sms_marketing_consent": {
"state": "not_subscribed",
"opt_in_level": "single_opt_in",
"consent_updated_at": "2024-01-01T07:00:00-05:00",
"consent_collected_from": "OTHER"
},
"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
}
}
}

Anchor to GET request, Retrieves all orders that belong to a customer
get
Retrieves all orders that belong to a customer

customer

Retrieves all orders that belong to a customer. By default, only open orders are returned. The query string parameters in the Order resource are also available at this endpoint.

Anchor to Parameters of Retrieves all orders that belong to a customerParameters

api_version
string
required
customer_id
string
required
status
enum
default open

The status of the orders to return.

Show status properties

  • open: Show only open orders.

  • closed: Show only closed orders.

  • cancelled: Show only canceled orders.

  • any: Show orders of any status, including archived orders.

Was this section helpful?

Anchor to get-customers-customer-id-orders-examplesExamples

Retrieve all open orders from a customer

Path parameters
customer_id=207119551
string
required

Retrieve all previous orders from a customer.

Path parameters
customer_id=207119551
string
required
Query parameters
status=any
enum
default open

The status of the orders to return.

Show status properties

  • open: Show only open orders.

  • closed: Show only closed orders.

  • cancelled: Show only canceled orders.

  • any: Show orders of any status, including archived orders.

Was this section helpful?
get

/admin/api/2025-07/customers/207119551/orders.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/customers/207119551/orders.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"orders": [
{
"id": 450789469,
"admin_graphql_api_id": "gid://shopify/Order/450789469",
"app_id": null,
"browser_ip": "0.0.0.0",
"buyer_accepts_marketing": false,
"cancel_reason": null,
"cancelled_at": null,
"cart_token": "68778783ad298f1c80c3bafcddeea02f",
"checkout_id": 901414060,
"checkout_token": "bd5a8aa1ecd019dd3520ff791ee3a24c",
"client_details": {
"accept_language": null,
"browser_height": null,
"browser_ip": "0.0.0.0",
"browser_width": null,
"session_hash": null,
"user_agent": null
},
"closed_at": null,
"confirmation_number": null,
"confirmed": true,
"contact_email": "bob.norman@mail.example.com",
"created_at": "2008-01-10T11:00:00-05:00",
"currency": "USD",
"current_subtotal_price": "195.67",
"current_subtotal_price_set": {
"shop_money": {
"amount": "195.67",
"currency_code": "USD"
},
"presentment_money": {
"amount": "195.67",

Anchor to GET request, Retrieves a count of customers
get
Retrieves a count of customers

customersCount
Requires customers access scope.

Retrieves a count of all customers.

Anchor to Parameters of Retrieves a count of customersParameters

api_version
string
required
created_at_max

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

created_at_min

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

updated_at_max

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

updated_at_min

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

Was this section helpful?

Anchor to get-customers-count-examplesExamples

Retrieve a count of all customers

Retrieve a count of customers changed after a specified date

Query parameters
updated_at_min=2025-06-30+18:32:28

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

Retrieve a count of customers created after a specified date

Query parameters
created_at_min=2025-06-30+18:32:07

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

Was this section helpful?
get

/admin/api/2025-07/customers/count.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/customers/count.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"count": 2
}

Anchor to GET request, Searches for customers that match a supplied query
get
Searches for customers that match a supplied query

customers
Requires customers access scope.

Searches for customers that match a supplied query. Note: This endpoint implements pagination by using links that are provided in the response header. To learn more, refer to Make paginated requests to the REST Admin API.

Anchor to Parameters of Searches for customers that match a supplied queryParameters

api_version
string
required
fields

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

limit
≤ 250
default 50

The maximum number of results to show.

order
default last_order_date DESC

Set the field and direction by which to order results.

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.

Was this section helpful?

Anchor to get-customers-search?query=email:bob.norman@mail.example.com-examplesExamples

Search for a customer with a specified email address

Query parameters
query=email:bob.norman@mail.example.com

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.

Search for all customers with a specified last name and show certain fields

Query parameters
fields=id,+email,+first_name,+last_name

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

query=last_name:Norman

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.

Search for all customers with a specified tag and show only certain fields

Query parameters
fields=id,+email,+first_name,+last_name,+tags

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

query=customer_tag:New+Customer

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.

Search for all customers with an address in the United States and a specified first name

Query parameters
query=first_name:Bob+country:United+States

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.

Search for customers matching a specified email domain

Query parameters
query=email:*@mail.example.com

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.

Search for customers who have verified their email address and show only certain fields

Query parameters
fields=id,+email,+first_name,+last_name,+verified_email

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

query=verified_email:true

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.

Was this section helpful?
get

/admin/api/2025-07/customers/search.json?query=email:bob.norman@mail.example.com

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/customers/search.json?query=email%3Abob.norman%40mail.example.com" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"customers": [
{
"id": 207119551,
"email": "bob.norman@mail.example.com",
"created_at": "2025-07-01T14:33:50-04:00",
"updated_at": "2025-07-01T14:33:50-04: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,
"tags": "Léon, Noël",
"last_order_name": "#1001",
"currency": "USD",
"phone": "+16136120707",
"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
}
],
"tax_exemptions": [],
"email_marketing_consent": {
"state": "not_subscribed",
"opt_in_level": null,
"consent_updated_at": "2004-06-13T11:57:11-04:00"
},
"sms_marketing_consent": {
"state": "not_subscribed",
"opt_in_level": "single_opt_in",
"consent_updated_at": "2024-01-01T07:00:00-05:00",
"consent_collected_from": "OTHER"
},
"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
}
}
]
}

Anchor to PUT request, Updates a customer
put
Updates a customer

customerUpdate
Requires customers access scope.

Updates a customer.

Anchor to Parameters of Updates a customerParameters

api_version
string
required
customer_id
string
required
Was this section helpful?

Anchor to put-customers-customer-id-examplesExamples

Add metafield to an existing customer

Path parameters
customer_id=207119551
string
required
Request body
customer
Customer resource
Show customer properties
customer.id:207119551

A unique identifier for the customer.

Update a customer's tags

Path parameters
customer_id=207119551
string
required
Request body
customer
Customer resource
Show customer properties
customer.id:207119551

A unique identifier for the customer.

customer.tags:"New Customer, Repeat Customer"
->
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.

Update details for a customer

Path parameters
customer_id=207119551
string
required
Request body
customer
Customer resource
Show customer properties
customer.id:207119551

A unique identifier for the customer.

customer.email:"changed@example.com"
->
email

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

customer.note:"Customer is a great guy"
->
note

A note about the customer.

Updating a customer that doesn't exist returns an error

Path parameters
customer_id=123
string
required
Request body
customer
Customer resource
Show customer properties
customer.id:123

A unique identifier for the customer.

customer.tags:"New Customer, Repeat Customer"
->
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.

Was this section helpful?
put

/admin/api/2025-07/customers/207119551.json

curl -d '{"customer":{"id":207119551,"metafields":[{"key":"new","value":"newvalue","type":"single_line_text_field","namespace":"global"}]}}' \
-X PUT "https://your-development-store.myshopify.com/admin/api/2025-07/customers/207119551.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"

{}

Response

JSON
HTTP/1.1 200 OK
{
"customer": {
"email": "bob.norman@mail.example.com",
"first_name": "Bob",
"last_name": "Norman",
"id": 207119551,
"created_at": "2025-07-01T14:35:46-04:00",
"updated_at": "2025-07-01T14:35:46-04:00",
"orders_count": 1,
"state": "disabled",
"total_spent": "199.65",
"last_order_id": 450789469,
"note": null,
"verified_email": true,
"multipass_identifier": null,
"tax_exempt": false,
"tags": "Léon, Noël",
"last_order_name": "#1001",
"currency": "USD",
"phone": "+16136120707",
"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
}
],
"tax_exemptions": [],
"email_marketing_consent": {
"state": "not_subscribed",
"opt_in_level": null,
"consent_updated_at": "2004-06-13T11:57:11-04:00"
},
"sms_marketing_consent": {
"state": "not_subscribed",
"opt_in_level": "single_opt_in",
"consent_updated_at": "2024-01-01T07:00:00-05:00",
"consent_collected_from": "OTHER"
},
"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
}
}
}

Anchor to DELETE request, Deletes a customer
del
Deletes a customer

customerDelete
Requires customers access scope.

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

Anchor to Parameters of Deletes a customerParameters

api_version
string
required
customer_id
string
required
Was this section helpful?

Anchor to delete-customers-customer-id-examplesExamples

Remove an existing customer

Path parameters
customer_id=207119551
string
required
Was this section helpful?
del

/admin/api/2025-07/customers/207119551.json

curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2025-07/customers/207119551.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{}