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
- post/admin/api/latest/customers.
json Creates a customer - post/admin/api/latest/customers/{customer_
id}/account_ activation_ url. json Creates an account activation URL for a customer - post/admin/api/latest/customers/{customer_
id}/send_ invite. json Sends an account invite to a customer - get/admin/api/latest/customers.
json?ids=207119551,562393516,688973684,1073339479 Retrieves a list of customers - get/admin/api/latest/customers/{customer_
id}. json Retrieves a single customer - get/admin/api/latest/customers/{customer_
id}/orders. json Retrieves all orders that belong to a customer - get/admin/api/latest/customers/count.
json Retrieves a count of customers - get/admin/api/latest/customers/search.
json?query=email:bob. norman@mail. example. com Searches for customers that match a supplied query - put/admin/api/latest/customers/{customer_
id}. json Updates a customer - del/admin/api/latest/customers/{customer_
id}. json Deletes a customer
Anchor to
The Customer resource
Anchor to
Properties
addresses
A list of the ten most recently updated addresses for the customer. Each address has the following properties:
Show addresses 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.
The default address for the customer. The default address has the following properties:
Show default_address 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
truefor 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
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
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
The customer's first name.
id
->
id
A unique identifier for the customer.
last_name
->
lastName
The customer's last name.
The ID of the customer's last order.
The name of the customer's last order. This is directly related to the name field on the Order resource.
metafield
Attaches additional metadata to a shop's resources:
Show metafield properties
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 customerpostCreates a customer
post
Creates a customer
Requires
customers access scope.Creates a customer.
api_version
string
required
Was this section helpful?
Create a customer with password and password_confirmation and skip sending the welcome email
Create a customer with password and password_confirmation and skip sending the welcome email
Request body
Show customer properties
Show customer properties
customer.first_
The customer's first name.
customer.last_
->
lastName
The customer's last name.
customer.email:
->
email
The unique email address of the customer. Attempting to assign the same email address to multiple customers returns an error.
customer.phone:
->
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
Show phone properties
- 6135551212
- +16135551212
- (613)555-1212
- +1 613-555-1212
customer.verified_
read-only
Whether the customer has verified their email address.
customer.addresses:
A list of the ten most recently updated addresses for the customer. Each address has the following properties:
Show addresses 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:
deprecated
The customer's password.
customer.password_
deprecated
The customer's password that's confirmed.
Create a customer with send_email_invite
Create a customer with send_email_invite
Request body
Show customer properties
Show customer properties
customer.first_
The customer's first name.
customer.last_
->
lastName
The customer's last name.
customer.email:
->
email
The unique email address of the customer. Attempting to assign the same email address to multiple customers returns an error.
customer.phone:
->
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
Show phone properties
- 6135551212
- +16135551212
- (613)555-1212
- +1 613-555-1212
customer.verified_
read-only
Whether the customer has verified their email address.
customer.addresses:
A list of the ten most recently updated addresses for the customer. Each address has the following properties:
Show addresses 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
Create a customer with a metafield
Request body
Show customer properties
Show customer properties
customer.first_
The customer's first name.
customer.last_
->
lastName
The customer's last name.
customer.email:
->
email
The unique email address of the customer. Attempting to assign the same email address to multiple customers returns an error.
customer.phone:
->
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
Show phone properties
- 6135551212
- +16135551212
- (613)555-1212
- +1 613-555-1212
customer.verified_
read-only
Whether the customer has verified their email address.
customer.addresses:
A list of the ten most recently updated addresses for the customer. Each address has the following properties:
Show addresses 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
Create a new customer record
Request body
Show customer properties
Show customer properties
customer.first_
The customer's first name.
customer.last_
->
lastName
The customer's last name.
customer.email:
->
email
The unique email address of the customer. Attempting to assign the same email address to multiple customers returns an error.
customer.phone:
->
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
Show phone properties
- 6135551212
- +16135551212
- (613)555-1212
- +1 613-555-1212
customer.verified_
read-only
Whether the customer has verified their email address.
customer.addresses:
A list of the ten most recently updated addresses for the customer. Each address has the following properties:
Show addresses 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
Creating a customer with a phone number that belongs to an existing customer returns an error
Request body
Show customer properties
Show customer properties
customer.phone:
->
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
Show phone properties
- 6135551212
- +16135551212
- (613)555-1212
- +1 613-555-1212
customer.first_
The customer's first name.
customer.last_
->
lastName
The customer's last name.
Creating a customer with an email that belongs to an existing customer returns an error
Creating a customer with an email that belongs to an existing customer returns an error
Request body
Show customer properties
Show customer properties
Creating a customer without an email or name fails and returns an error
Creating a customer without an email or name fails and returns an error
Request body
Was this section helpful?
post
/admin/api/2025-10/customers.
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-10/customers.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}
Response
JSON
HTTP/1.1 201 Created
{
"customer": {
"first_name": "Steve",
"last_name": "Lastnameson",
"updated_at": "2025-10-01T15:00:48-04:00",
"id": 1073339472,
"created_at": "2025-10-01T15:00:47-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,
"email": "steve.lastnameson@example.com",
"phone": "+15142546011",
"currency": "USD",
"addresses": [
{
"id": 1053317300,
"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
}
],
"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/1073339472",
"default_address": {
"id": 1053317300,
"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": false
}
}
}
examples
Create a customer with <code>password</code> and <code>password_confirmation</code> and skip sending the welcome email
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-10/customers.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json"const { admin, session } = await authenticate.admin(request); const customer = new admin.rest.resources.Customer({session: session}); customer.first_name = "Steve"; customer.last_name = "Lastnameson"; customer.email = "steve.lastnameson@example.com"; customer.phone = "+15142546011"; customer.verified_email = true; customer.addresses = [ { "address1": "123 Oak St", "city": "Ottawa", "province": "ON", "phone": "555-1212", "zip": "123 ABC", "last_name": "Lastnameson", "first_name": "Mother", "country": "CA" } ]; customer.password = "newpass"; customer.password_confirmation = "newpass"; customer.send_email_welcome = false; await customer.save({ update: true, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session customer = ShopifyAPI::Customer.new(session: test_session) customer.first_name = "Steve" customer.last_name = "Lastnameson" customer.email = "steve.lastnameson@example.com" customer.phone = "+15142546011" customer.verified_email = true customer.addresses = [ { "address1" => "123 Oak St", "city" => "Ottawa", "province" => "ON", "phone" => "555-1212", "zip" => "123 ABC", "last_name" => "Lastnameson", "first_name" => "Mother", "country" => "CA" } ] customer.password = "newpass" customer.password_confirmation = "newpass" customer.send_email_welcome = false customer.save!// Session is built by the OAuth process const customer = new shopify.rest.Customer({session: session}); customer.first_name = "Steve"; customer.last_name = "Lastnameson"; customer.email = "steve.lastnameson@example.com"; customer.phone = "+15142546011"; customer.verified_email = true; customer.addresses = [ { "address1": "123 Oak St", "city": "Ottawa", "province": "ON", "phone": "555-1212", "zip": "123 ABC", "last_name": "Lastnameson", "first_name": "Mother", "country": "CA" } ]; customer.password = "newpass"; customer.password_confirmation = "newpass"; customer.send_email_welcome = false; await customer.save({ update: true, });response
HTTP/1.1 201 Created{"customer":{"first_name":"Steve","last_name":"Lastnameson","updated_at":"2025-10-01T15:00:48-04:00","id":1073339472,"created_at":"2025-10-01T15:00:47-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,"email":"steve.lastnameson@example.com","phone":"+15142546011","currency":"USD","addresses":[{"id":1053317300,"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}],"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/1073339472","default_address":{"id":1053317300,"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":false}}}Create a customer with <code>send_email_invite</code>
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"}],"send_email_invite":true}}' \ -X POST "https://your-development-store.myshopify.com/admin/api/2025-10/customers.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json"const { admin, session } = await authenticate.admin(request); const customer = new admin.rest.resources.Customer({session: session}); customer.first_name = "Steve"; customer.last_name = "Lastnameson"; customer.email = "steve.lastnameson@example.com"; customer.phone = "+15142546011"; customer.verified_email = true; customer.addresses = [ { "address1": "123 Oak St", "city": "Ottawa", "province": "ON", "phone": "555-1212", "zip": "123 ABC", "last_name": "Lastnameson", "first_name": "Mother", "country": "CA" } ]; customer.send_email_invite = true; await customer.save({ update: true, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session customer = ShopifyAPI::Customer.new(session: test_session) customer.first_name = "Steve" customer.last_name = "Lastnameson" customer.email = "steve.lastnameson@example.com" customer.phone = "+15142546011" customer.verified_email = true customer.addresses = [ { "address1" => "123 Oak St", "city" => "Ottawa", "province" => "ON", "phone" => "555-1212", "zip" => "123 ABC", "last_name" => "Lastnameson", "first_name" => "Mother", "country" => "CA" } ] customer.send_email_invite = true customer.save!// Session is built by the OAuth process const customer = new shopify.rest.Customer({session: session}); customer.first_name = "Steve"; customer.last_name = "Lastnameson"; customer.email = "steve.lastnameson@example.com"; customer.phone = "+15142546011"; customer.verified_email = true; customer.addresses = [ { "address1": "123 Oak St", "city": "Ottawa", "province": "ON", "phone": "555-1212", "zip": "123 ABC", "last_name": "Lastnameson", "first_name": "Mother", "country": "CA" } ]; customer.send_email_invite = true; await customer.save({ update: true, });response
HTTP/1.1 201 Created{"customer":{"first_name":"Steve","last_name":"Lastnameson","updated_at":"2025-10-01T15:03:38-04:00","id":1073339478,"created_at":"2025-10-01T15:03:38-04:00","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,"email":"steve.lastnameson@example.com","phone":"+15142546011","currency":"USD","addresses":[{"id":1053317306,"customer_id":1073339478,"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/1073339478","default_address":{"id":1053317306,"customer_id":1073339478,"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}}}Create a customer with a metafield
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"}],"metafields":[{"key":"new","value":"newvalue","type":"single_line_text_field","namespace":"global"}]}}' \ -X POST "https://your-development-store.myshopify.com/admin/api/2025-10/customers.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json"const { admin, session } = await authenticate.admin(request); const customer = new admin.rest.resources.Customer({session: session}); customer.first_name = "Steve"; customer.last_name = "Lastnameson"; customer.email = "steve.lastnameson@example.com"; customer.phone = "+15142546011"; customer.verified_email = true; customer.addresses = [ { "address1": "123 Oak St", "city": "Ottawa", "province": "ON", "phone": "555-1212", "zip": "123 ABC", "last_name": "Lastnameson", "first_name": "Mother", "country": "CA" } ]; customer.metafields = [ { "key": "new", "value": "newvalue", "type": "single_line_text_field", "namespace": "global" } ]; await customer.save({ update: true, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session customer = ShopifyAPI::Customer.new(session: test_session) customer.first_name = "Steve" customer.last_name = "Lastnameson" customer.email = "steve.lastnameson@example.com" customer.phone = "+15142546011" customer.verified_email = true customer.addresses = [ { "address1" => "123 Oak St", "city" => "Ottawa", "province" => "ON", "phone" => "555-1212", "zip" => "123 ABC", "last_name" => "Lastnameson", "first_name" => "Mother", "country" => "CA" } ] customer.metafields = [ { "key" => "new", "value" => "newvalue", "type" => "single_line_text_field", "namespace" => "global" } ] customer.save!// Session is built by the OAuth process const customer = new shopify.rest.Customer({session: session}); customer.first_name = "Steve"; customer.last_name = "Lastnameson"; customer.email = "steve.lastnameson@example.com"; customer.phone = "+15142546011"; customer.verified_email = true; customer.addresses = [ { "address1": "123 Oak St", "city": "Ottawa", "province": "ON", "phone": "555-1212", "zip": "123 ABC", "last_name": "Lastnameson", "first_name": "Mother", "country": "CA" } ]; customer.metafields = [ { "key": "new", "value": "newvalue", "type": "single_line_text_field", "namespace": "global" } ]; await customer.save({ update: true, });response
HTTP/1.1 201 Created{"customer":{"first_name":"Steve","last_name":"Lastnameson","updated_at":"2025-10-01T15:02:24-04:00","id":1073339476,"created_at":"2025-10-01T15:02:24-04:00","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,"email":"steve.lastnameson@example.com","phone":"+15142546011","currency":"USD","addresses":[{"id":1053317304,"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}],"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/1073339476","default_address":{"id":1053317304,"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":false}}}Create a new customer record
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"}]}}' \ -X POST "https://your-development-store.myshopify.com/admin/api/2025-10/customers.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json"const { admin, session } = await authenticate.admin(request); const customer = new admin.rest.resources.Customer({session: session}); customer.first_name = "Steve"; customer.last_name = "Lastnameson"; customer.email = "steve.lastnameson@example.com"; customer.phone = "+15142546011"; customer.verified_email = true; customer.addresses = [ { "address1": "123 Oak St", "city": "Ottawa", "province": "ON", "phone": "555-1212", "zip": "123 ABC", "last_name": "Lastnameson", "first_name": "Mother", "country": "CA" } ]; await customer.save({ update: true, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session customer = ShopifyAPI::Customer.new(session: test_session) customer.first_name = "Steve" customer.last_name = "Lastnameson" customer.email = "steve.lastnameson@example.com" customer.phone = "+15142546011" customer.verified_email = true customer.addresses = [ { "address1" => "123 Oak St", "city" => "Ottawa", "province" => "ON", "phone" => "555-1212", "zip" => "123 ABC", "last_name" => "Lastnameson", "first_name" => "Mother", "country" => "CA" } ] customer.save!// Session is built by the OAuth process const customer = new shopify.rest.Customer({session: session}); customer.first_name = "Steve"; customer.last_name = "Lastnameson"; customer.email = "steve.lastnameson@example.com"; customer.phone = "+15142546011"; customer.verified_email = true; customer.addresses = [ { "address1": "123 Oak St", "city": "Ottawa", "province": "ON", "phone": "555-1212", "zip": "123 ABC", "last_name": "Lastnameson", "first_name": "Mother", "country": "CA" } ]; await customer.save({ update: true, });response
HTTP/1.1 201 Created{"customer":{"first_name":"Steve","last_name":"Lastnameson","updated_at":"2025-10-01T15:02:48-04:00","id":1073339477,"created_at":"2025-10-01T15:02:48-04:00","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,"email":"steve.lastnameson@example.com","phone":"+15142546011","currency":"USD","addresses":[{"id":1053317305,"customer_id":1073339477,"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/1073339477","default_address":{"id":1053317305,"customer_id":1073339477,"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}}}Creating a customer with a phone number that belongs to an existing customer returns an error
curl -d '{"customer":{"phone":"+16136120707","first_name":"Tobi","last_name":"Lutke"}}' \ -X POST "https://your-development-store.myshopify.com/admin/api/2025-10/customers.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json"const { admin, session } = await authenticate.admin(request); const customer = new admin.rest.resources.Customer({session: session}); customer.phone = "+16136120707"; customer.first_name = "Tobi"; customer.last_name = "Lutke"; await customer.save({ update: true, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session customer = ShopifyAPI::Customer.new(session: test_session) customer.phone = "+16136120707" customer.first_name = "Tobi" customer.last_name = "Lutke" customer.save!// Session is built by the OAuth process const customer = new shopify.rest.Customer({session: session}); customer.phone = "+16136120707"; customer.first_name = "Tobi"; customer.last_name = "Lutke"; await customer.save({ update: true, });response
HTTP/1.1 422 Unprocessable Entity{"errors":{"phone":["has already been taken"]}}Creating a customer with an email that belongs to an existing customer returns an error
curl -d '{"customer":{"email":"bob.norman@mail.example.com","first_name":"Tobi","last_name":"Lutke"}}' \ -X POST "https://your-development-store.myshopify.com/admin/api/2025-10/customers.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json"const { admin, session } = await authenticate.admin(request); const customer = new admin.rest.resources.Customer({session: session}); customer.email = "bob.norman@mail.example.com"; customer.first_name = "Tobi"; customer.last_name = "Lutke"; await customer.save({ update: true, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session customer = ShopifyAPI::Customer.new(session: test_session) customer.email = "bob.norman@mail.example.com" customer.first_name = "Tobi" customer.last_name = "Lutke" customer.save!// Session is built by the OAuth process const customer = new shopify.rest.Customer({session: session}); customer.email = "bob.norman@mail.example.com"; customer.first_name = "Tobi"; customer.last_name = "Lutke"; await customer.save({ update: true, });response
HTTP/1.1 422 Unprocessable Entity{"errors":{"email":["has already been taken"]}}Creating a customer without an email or name fails and returns an error
curl -d '{"customer":{"email":null,"first_name":null,"last_name":null}}' \ -X POST "https://your-development-store.myshopify.com/admin/api/2025-10/customers.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json"const { admin, session } = await authenticate.admin(request); const customer = new admin.rest.resources.Customer({session: session}); customer.email = null; customer.first_name = null; customer.last_name = null; await customer.save({ update: true, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session customer = ShopifyAPI::Customer.new(session: test_session) customer.email = nil customer.first_name = nil customer.last_name = nil customer.save!// Session is built by the OAuth process const customer = new shopify.rest.Customer({session: session}); customer.email = null; customer.first_name = null; customer.last_name = null; await customer.save({ update: true, });response
HTTP/1.1 422 Unprocessable Entity{"errors":{"base":["A name, phone number, or email address must be present"]}}
Anchor to POST request, Creates an account activation URL for a customerpostCreates an account activation URL for a customer
post
Creates an account activation URL for a customer
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.
api_version
string
required
customer_id
string
required
Was this section helpful?
Create an account activation URL for an invited or disabled customer
Create an account activation URL for an invited or disabled customer
Path parameters
customer_
string
required
Creating an account activation URL for an enabled customer fails and returns an error
Creating an account activation URL for an enabled customer fails and returns an error
Path parameters
customer_
string
required
Was this section helpful?
post
/admin/api/2025-10/customers/207119551/account_
curl -d '{}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2025-10/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/d6923e9c467a14a37576345ece92bab0-1759345202"
}
examples
Create an account activation URL for an invited or disabled customer
curl -d '{}' \ -X POST "https://your-development-store.myshopify.com/admin/api/2025-10/customers/207119551/account_activation_url.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json"const { admin, session } = await authenticate.admin(request); const customer = new admin.rest.resources.Customer({session: session}); customer.id = 207119551; await customer.account_activation_url({});# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session customer = ShopifyAPI::Customer.new(session: test_session) customer.id = 207119551 customer.account_activation_url( session: test_session, )// Session is built by the OAuth process const customer = new shopify.rest.Customer({session: session}); customer.id = 207119551; await customer.account_activation_url({});response
HTTP/1.1 200 OK{"account_activation_url":"https://jsmith.myshopify.com/account/activate/207119551/d6923e9c467a14a37576345ece92bab0-1759345202"}Creating an account activation URL for an enabled customer fails and returns an error
curl -d '{}' \ -X POST "https://your-development-store.myshopify.com/admin/api/2025-10/customers/207119551/account_activation_url.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json"const { admin, session } = await authenticate.admin(request); const customer = new admin.rest.resources.Customer({session: session}); customer.id = 207119551; await customer.account_activation_url({});# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session customer = ShopifyAPI::Customer.new(session: test_session) customer.id = 207119551 customer.account_activation_url( session: test_session, )// Session is built by the OAuth process const customer = new shopify.rest.Customer({session: session}); customer.id = 207119551; await customer.account_activation_url({});response
HTTP/1.1 422 Unprocessable Entity{"errors":["account already enabled"]}
Anchor to POST request, Sends an account invite to a customerpostSends an account invite to a customer
post
Sends an account invite to a customer
Requires
customers access scope.Sends an account invite to a customer.
api_version
string
required
customer_id
string
required
Was this section helpful?
Send a customized invite
Send a customized invite
Path parameters
customer_
string
required
Send the default invite
Send the default invite
Path parameters
customer_
string
required
Was this section helpful?
post
/admin/api/2025-10/customers/207119551/send_
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-10/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"
]
}
}
examples
Send a customized invite
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-10/customers/207119551/send_invite.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json"const { admin, session } = await authenticate.admin(request); const customer = new admin.rest.resources.Customer({session: session}); customer.id = 207119551; await customer.send_invite({ body: {"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"}}, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session customer = ShopifyAPI::Customer.new(session: test_session) customer.id = 207119551 customer.send_invite( session: test_session, body: {"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"}}, )// Session is built by the OAuth process const customer = new shopify.rest.Customer({session: session}); customer.id = 207119551; await customer.send_invite({ body: {"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"}}, });response
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"]}}Send the default invite
curl -d '{"customer_invite":{}}' \ -X POST "https://your-development-store.myshopify.com/admin/api/2025-10/customers/207119551/send_invite.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json"const { admin, session } = await authenticate.admin(request); const customer = new admin.rest.resources.Customer({session: session}); customer.id = 207119551; await customer.send_invite({ body: {"customer_invite": {}}, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session customer = ShopifyAPI::Customer.new(session: test_session) customer.id = 207119551 customer.send_invite( session: test_session, body: {"customer_invite" => {}}, )// Session is built by the OAuth process const customer = new shopify.rest.Customer({session: session}); customer.id = 207119551; await customer.send_invite({ body: {"customer_invite": {}}, });response
HTTP/1.1 201 Created{"customer_invite":{"to":"bob.norman@mail.example.com","from":"j.smith@example.com","subject":"Customer account activation","custom_message":"","bcc":[]}}
Anchor to GET request, Retrieves a list of customersgetRetrieves a list of customers
get
Retrieves a list of 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.
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?
Retrieve a list of specific customers
Retrieve a list of specific customers
Query parameters
ids=
Restrict results to customers specified by a comma-separated list of IDs.
Retrieve all customers after a specified ID
Retrieve all customers after a specified ID
Query parameters
since_
Restrict results to those after the specified ID.
Retrieve all customers changed after a certain date
Retrieve all customers changed after a certain date
Query parameters
updated_
Show customers last updated after a specified date.
(format: 2014-04-25T16:15:47-04:00)
Retrieve all customers for a shop
Retrieve all customers for a shop
Retrieve only the specified customer fields
Retrieve only the specified customer fields
Query parameters
fields=
Show only certain fields, specified by a comma-separated list of field names.
Was this section helpful?
get
/admin/api/2025-10/customers.
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/customers.json?ids=207119551%2C562393516%2C688973684%2C1073339479" \
-H "X-Shopify-Access-Token: {access_token}"
{}
Response
JSON
HTTP/1.1 200 OK
{
"customers": [
{
"id": 1073339479,
"created_at": "2025-10-01T15:03:54-04:00",
"updated_at": "2025-10-01T15:03:54-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,
"email": "steve.lastnameson@example.com",
"phone": "+15142546011",
"currency": "USD",
"addresses": [
{
"id": 1053317307,
"customer_id": 1073339479,
"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",
examples
Retrieve a list of specific customers
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/customers.json?ids=207119551%2C562393516%2C688973684%2C1073339479" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.Customer.all({ session: session, ids: "207119551,562393516,688973684,1073339479", });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::Customer.all( session: test_session, ids: "207119551,562393516,688973684,1073339479", )// Session is built by the OAuth process await shopify.rest.Customer.all({ session: session, ids: "207119551,562393516,688973684,1073339479", });response
HTTP/1.1 200 OK{"customers":[{"id":1073339479,"created_at":"2025-10-01T15:03:54-04:00","updated_at":"2025-10-01T15:03:54-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,"email":"steve.lastnameson@example.com","phone":"+15142546011","currency":"USD","addresses":[{"id":1053317307,"customer_id":1073339479,"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/1073339479","default_address":{"id":1053317307,"customer_id":1073339479,"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":688973684,"created_at":"2025-10-01T15:03:46-04:00","updated_at":"2025-10-01T15:03:46-04:00","first_name":"Bob","last_name":"Norman Invalid","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,"email":"bob.norman.invalid@mail.example.de","phone":null,"currency":"USD","addresses":[],"tax_exemptions":[],"email_marketing_consent":{"state":"invalid","opt_in_level":null,"consent_updated_at":"2004-06-13T11:57:11-04:00"},"sms_marketing_consent":null,"admin_graphql_api_id":"gid://shopify/Customer/688973684"},{"id":562393516,"created_at":"2025-10-01T15:03:46-04:00","updated_at":"2025-10-01T15:03:46-04:00","first_name":"Dom","last_name":"Toretto","orders_count":0,"state":"disabled","total_spent":"199.65","last_order_id":450789469,"note":null,"verified_email":true,"multipass_identifier":null,"tax_exempt":false,"tags":"","last_order_name":"#1001","email":"dom.toretto@mail.example.com","phone":"+12016251199","currency":"USD","addresses":[{"id":562393516,"customer_id":562393516,"first_name":"Dom","last_name":"Toretto","company":null,"address1":"Chestnut Street 93","address2":"","city":"Louisville","province":"Kentucky","country":"United States","zip":"40202","phone":"+1(201)625-1199","name":"Dom Toretto","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":null,"admin_graphql_api_id":"gid://shopify/Customer/562393516","default_address":{"id":562393516,"customer_id":562393516,"first_name":"Dom","last_name":"Toretto","company":null,"address1":"Chestnut Street 93","address2":"","city":"Louisville","province":"Kentucky","country":"United States","zip":"40202","phone":"+1(201)625-1199","name":"Dom Toretto","province_code":"KY","country_code":"US","country_name":"United States","default":true}},{"id":207119551,"created_at":"2025-10-01T15:03:46-04:00","updated_at":"2025-10-01T15:03:46-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","email":"bob.norman@mail.example.com","phone":"+16136120707","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}],"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}}]}Retrieve all customers after a specified ID
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/customers.json?since_id=207119551" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.Customer.all({ session: session, since_id: "207119551", });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::Customer.all( session: test_session, since_id: "207119551", )// Session is built by the OAuth process await shopify.rest.Customer.all({ session: session, since_id: "207119551", });response
HTTP/1.1 200 OK{"customers":[{"id":562393516,"created_at":"2025-10-01T15:01:28-04:00","updated_at":"2025-10-01T15:01:28-04:00","first_name":"Dom","last_name":"Toretto","orders_count":0,"state":"disabled","total_spent":"199.65","last_order_id":450789469,"note":null,"verified_email":true,"multipass_identifier":null,"tax_exempt":false,"tags":"","last_order_name":"#1001","email":"dom.toretto@mail.example.com","phone":"+12016251199","currency":"USD","addresses":[{"id":562393516,"customer_id":562393516,"first_name":"Dom","last_name":"Toretto","company":null,"address1":"Chestnut Street 93","address2":"","city":"Louisville","province":"Kentucky","country":"United States","zip":"40202","phone":"+1(201)625-1199","name":"Dom Toretto","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":null,"admin_graphql_api_id":"gid://shopify/Customer/562393516","default_address":{"id":562393516,"customer_id":562393516,"first_name":"Dom","last_name":"Toretto","company":null,"address1":"Chestnut Street 93","address2":"","city":"Louisville","province":"Kentucky","country":"United States","zip":"40202","phone":"+1(201)625-1199","name":"Dom Toretto","province_code":"KY","country_code":"US","country_name":"United States","default":true}},{"id":688973684,"created_at":"2025-10-01T15:01:28-04:00","updated_at":"2025-10-01T15:01:28-04:00","first_name":"Bob","last_name":"Norman Invalid","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,"email":"bob.norman.invalid@mail.example.de","phone":null,"currency":"USD","addresses":[],"tax_exemptions":[],"email_marketing_consent":{"state":"invalid","opt_in_level":null,"consent_updated_at":"2004-06-13T11:57:11-04:00"},"sms_marketing_consent":null,"admin_graphql_api_id":"gid://shopify/Customer/688973684"},{"id":1073339474,"created_at":"2025-10-01T15:01:35-04:00","updated_at":"2025-10-01T15:01:35-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,"email":"steve.lastnameson@example.com","phone":"+15142546011","currency":"USD","addresses":[{"id":1053317302,"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}],"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/1073339474","default_address":{"id":1053317302,"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}}]}Retrieve all customers changed after a certain date
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/customers.json?updated_at_min=2025-09-30+19%3A00%3A55" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.Customer.all({ session: session, updated_at_min: "2025-09-30 19:00:55", });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::Customer.all( session: test_session, updated_at_min: "2025-09-30 19:00:55", )// Session is built by the OAuth process await shopify.rest.Customer.all({ session: session, updated_at_min: "2025-09-30 19:00:55", });response
HTTP/1.1 200 OK{"customers":[{"id":688973684,"created_at":"2025-10-01T15:00:48-04:00","updated_at":"2025-10-01T15:00:48-04:00","first_name":"Bob","last_name":"Norman Invalid","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,"email":"bob.norman.invalid@mail.example.de","phone":null,"currency":"USD","addresses":[],"tax_exemptions":[],"email_marketing_consent":{"state":"invalid","opt_in_level":null,"consent_updated_at":"2004-06-13T11:57:11-04:00"},"sms_marketing_consent":null,"admin_graphql_api_id":"gid://shopify/Customer/688973684"},{"id":562393516,"created_at":"2025-10-01T15:00:48-04:00","updated_at":"2025-10-01T15:00:48-04:00","first_name":"Dom","last_name":"Toretto","orders_count":0,"state":"disabled","total_spent":"199.65","last_order_id":450789469,"note":null,"verified_email":true,"multipass_identifier":null,"tax_exempt":false,"tags":"","last_order_name":"#1001","email":"dom.toretto@mail.example.com","phone":"+12016251199","currency":"USD","addresses":[{"id":562393516,"customer_id":562393516,"first_name":"Dom","last_name":"Toretto","company":null,"address1":"Chestnut Street 93","address2":"","city":"Louisville","province":"Kentucky","country":"United States","zip":"40202","phone":"+1(201)625-1199","name":"Dom Toretto","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":null,"admin_graphql_api_id":"gid://shopify/Customer/562393516","default_address":{"id":562393516,"customer_id":562393516,"first_name":"Dom","last_name":"Toretto","company":null,"address1":"Chestnut Street 93","address2":"","city":"Louisville","province":"Kentucky","country":"United States","zip":"40202","phone":"+1(201)625-1199","name":"Dom Toretto","province_code":"KY","country_code":"US","country_name":"United States","default":true}},{"id":207119551,"created_at":"2025-10-01T15:00:48-04:00","updated_at":"2025-10-01T15:00:48-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","email":"bob.norman@mail.example.com","phone":"+16136120707","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}],"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}}]}Retrieve all customers for a shop
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/customers.json" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.Customer.all({ session: session, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::Customer.all( session: test_session, )// Session is built by the OAuth process await shopify.rest.Customer.all({ session: session, });response
HTTP/1.1 200 OK{"customers":[{"id":688973684,"created_at":"2025-10-01T15:03:13-04:00","updated_at":"2025-10-01T15:03:13-04:00","first_name":"Bob","last_name":"Norman Invalid","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,"email":"bob.norman.invalid@mail.example.de","phone":null,"currency":"USD","addresses":[],"tax_exemptions":[],"email_marketing_consent":{"state":"invalid","opt_in_level":null,"consent_updated_at":"2004-06-13T11:57:11-04:00"},"sms_marketing_consent":null,"admin_graphql_api_id":"gid://shopify/Customer/688973684"},{"id":562393516,"created_at":"2025-10-01T15:03:13-04:00","updated_at":"2025-10-01T15:03:13-04:00","first_name":"Dom","last_name":"Toretto","orders_count":0,"state":"disabled","total_spent":"199.65","last_order_id":450789469,"note":null,"verified_email":true,"multipass_identifier":null,"tax_exempt":false,"tags":"","last_order_name":"#1001","email":"dom.toretto@mail.example.com","phone":"+12016251199","currency":"USD","addresses":[{"id":562393516,"customer_id":562393516,"first_name":"Dom","last_name":"Toretto","company":null,"address1":"Chestnut Street 93","address2":"","city":"Louisville","province":"Kentucky","country":"United States","zip":"40202","phone":"+1(201)625-1199","name":"Dom Toretto","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":null,"admin_graphql_api_id":"gid://shopify/Customer/562393516","default_address":{"id":562393516,"customer_id":562393516,"first_name":"Dom","last_name":"Toretto","company":null,"address1":"Chestnut Street 93","address2":"","city":"Louisville","province":"Kentucky","country":"United States","zip":"40202","phone":"+1(201)625-1199","name":"Dom Toretto","province_code":"KY","country_code":"US","country_name":"United States","default":true}},{"id":207119551,"created_at":"2025-10-01T15:03:13-04:00","updated_at":"2025-10-01T15:03: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","email":"bob.norman@mail.example.com","phone":"+16136120707","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}],"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}}]}Retrieve only the specified customer fields
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/customers.json?fields=id%2Ctags%2Cemail" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.Customer.all({ session: session, fields: "id,tags,email", });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::Customer.all( session: test_session, fields: "id,tags,email", )// Session is built by the OAuth process await shopify.rest.Customer.all({ session: session, fields: "id,tags,email", });response
HTTP/1.1 200 OK{"customers":[{"id":688973684,"tags":"","email":"bob.norman.invalid@mail.example.de"},{"id":562393516,"tags":"","email":"dom.toretto@mail.example.com"},{"id":207119551,"tags":"Léon, Noël","email":"bob.norman@mail.example.com"}]}
Anchor to GET request, Retrieves a single customergetRetrieves a single customer
get
Retrieves a single customer
Requires
customers access scope.Retrieves a single customer.
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?
Retrieve a single customer by their ID
Retrieve a single customer by their ID
Path parameters
customer_
string
required
Was this section helpful?
get
/admin/api/2025-10/customers/207119551.
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/customers/207119551.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}
Response
JSON
HTTP/1.1 200 OK
{
"customer": {
"id": 207119551,
"created_at": "2025-10-01T15:01:53-04:00",
"updated_at": "2025-10-01T15:01:53-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",
"email": "bob.norman@mail.example.com",
"phone": "+16136120707",
"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
}
],
"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
}
}
}
examples
Retrieve a single customer by their ID
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/customers/207119551.json" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.Customer.find({ session: session, id: 207119551, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::Customer.find( session: test_session, id: 207119551, )// Session is built by the OAuth process await shopify.rest.Customer.find({ session: session, id: 207119551, });response
HTTP/1.1 200 OK{"customer":{"id":207119551,"created_at":"2025-10-01T15:01:53-04:00","updated_at":"2025-10-01T15:01:53-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","email":"bob.norman@mail.example.com","phone":"+16136120707","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}],"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 customergetRetrieves all orders that belong to a customer
get
Retrieves all orders that belong to a 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.
api_version
string
required
customer_id
string
required
status
enum
default open
The status of the orders to return.
Show status properties
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?
Retrieve all open orders from a customer
Retrieve all open orders from a customer
Path parameters
customer_
string
required
Retrieve all previous orders from a customer.
Retrieve all previous orders from a customer.
Path parameters
customer_
string
required
Query parameters
status=
enum
default open
The status of the orders to return.
Show status properties
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-10/customers/207119551/orders.
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/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",
examples
Retrieve all open orders from a customer
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/customers/207119551/orders.json" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.Customer.orders({ session: session, id: 207119551, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::Customer.orders( session: test_session, id: 207119551, )// Session is built by the OAuth process await shopify.rest.Customer.orders({ session: session, id: 207119551, });response
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","currency_code":"USD"}},"current_total_additional_fees_set":null,"current_total_discounts":"3.33","current_total_discounts_set":{"shop_money":{"amount":"3.33","currency_code":"USD"},"presentment_money":{"amount":"3.33","currency_code":"USD"}},"current_total_duties_set":null,"current_total_price":"199.65","current_total_price_set":{"shop_money":{"amount":"199.65","currency_code":"USD"},"presentment_money":{"amount":"199.65","currency_code":"USD"}},"current_total_tax":"3.98","current_total_tax_set":{"shop_money":{"amount":"3.98","currency_code":"USD"},"presentment_money":{"amount":"3.98","currency_code":"USD"}},"customer_locale":null,"device_id":null,"discount_codes":[{"code":"TENOFF","amount":"10.00","type":"fixed_amount"}],"duties_included":false,"email":"bob.norman@mail.example.com","estimated_taxes":false,"financial_status":"partially_refunded","fulfillment_status":null,"landing_site":"http://www.example.com?source=abc","landing_site_ref":"abc","location_id":null,"merchant_business_entity_id":"MTU0ODM4MDAwOQ","merchant_of_record_app_id":null,"name":"#1001","note":null,"note_attributes":[{"name":"custom engraving","value":"Happy Birthday"},{"name":"colour","value":"green"}],"number":1,"order_number":1001,"order_status_url":"https://jsmith.myshopify.com/548380009/orders/b1946ac92492d2347c6235b4d2611184/authenticate?key=imasecretipod","original_total_additional_fees_set":null,"original_total_duties_set":null,"payment_gateway_names":["bogus"],"phone":"+557734881234","po_number":"ABC123","presentment_currency":"USD","processed_at":"2008-01-10T11:00:00-05:00","reference":"fhwdgads","referring_site":"http://www.otherexample.com","source_identifier":"fhwdgads","source_name":"web","source_url":null,"subtotal_price":"597.00","subtotal_price_set":{"shop_money":{"amount":"597.00","currency_code":"USD"},"presentment_money":{"amount":"597.00","currency_code":"USD"}},"tags":"","tax_exempt":false,"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"}},"channel_liable":null}],"taxes_included":false,"test":false,"token":"b1946ac92492d2347c6235b4d2611184","total_cash_rounding_payment_adjustment_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"total_cash_rounding_refund_adjustment_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"total_discounts":"10.00","total_discounts_set":{"shop_money":{"amount":"10.00","currency_code":"USD"},"presentment_money":{"amount":"10.00","currency_code":"USD"}},"total_line_items_price":"597.00","total_line_items_price_set":{"shop_money":{"amount":"597.00","currency_code":"USD"},"presentment_money":{"amount":"597.00","currency_code":"USD"}},"total_outstanding":"0.00","total_price":"598.94","total_price_set":{"shop_money":{"amount":"598.94","currency_code":"USD"},"presentment_money":{"amount":"598.94","currency_code":"USD"}},"total_shipping_price_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"total_tax":"11.94","total_tax_set":{"shop_money":{"amount":"11.94","currency_code":"USD"},"presentment_money":{"amount":"11.94","currency_code":"USD"}},"total_tip_received":"0.00","total_weight":0,"updated_at":"2008-01-10T11:00:00-05:00","user_id":null,"billing_address":{"first_name":"Bob","address1":"Chestnut Street 92","phone":"+1(502)-459-2181","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,"created_at":"2025-10-01T15:03:05-04:00","updated_at":"2025-10-01T15:03:05-04:00","first_name":"Bob","last_name":"Norman","state":"disabled","note":null,"verified_email":true,"multipass_identifier":null,"tax_exempt":false,"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"},"tags":"Léon, Noël","email":"bob.norman@mail.example.com","phone":"+16136120707","currency":"USD","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}},"discount_applications":[{"target_type":"line_item","type":"discount_code","value":"10.0","value_type":"fixed_amount","allocation_method":"across","target_selection":"all","code":"TENOFF"}],"fulfillments":[{"id":255858046,"admin_graphql_api_id":"gid://shopify/Fulfillment/255858046","created_at":"2025-10-01T15:03:05-04:00","location_id":655441491,"name":"#1001.0","order_id":450789469,"origin_address":{},"receipt":{"testcase":true,"authorization":"123456"},"service":"manual","shipment_status":null,"status":"failure","tracking_company":"USPS","tracking_number":"1Z1234512345123456","tracking_numbers":["1Z1234512345123456"],"tracking_url":"https://tools.usps.com/go/TrackConfirmAction_input?qtc_tLabels1=1Z1234512345123456","tracking_urls":["https://tools.usps.com/go/TrackConfirmAction_input?qtc_tLabels1=1Z1234512345123456"],"updated_at":"2025-10-01T15:03:05-04:00","line_items":[{"id":466157049,"admin_graphql_api_id":"gid://shopify/LineItem/466157049","attributed_staffs":[],"current_quantity":0,"fulfillable_quantity":0,"fulfillment_service":"manual","fulfillment_status":null,"gift_card":false,"grams":200,"name":"IPod Nano - 8gb - green","price":"199.00","price_set":{"shop_money":{"amount":"199.00","currency_code":"USD"},"presentment_money":{"amount":"199.00","currency_code":"USD"}},"product_exists":true,"product_id":632910392,"properties":[{"name":"Custom Engraving Front","value":"Happy Birthday"},{"name":"Custom Engraving Back","value":"Merry Christmas"}],"quantity":1,"requires_shipping":true,"sku":"IPOD2008GREEN","taxable":true,"title":"IPod Nano - 8gb","total_discount":"0.00","total_discount_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"variant_id":39072856,"variant_inventory_management":"shopify","variant_title":"green","vendor":null,"tax_lines":[{"channel_liable":null,"price":"3.98","price_set":{"shop_money":{"amount":"3.98","currency_code":"USD"},"presentment_money":{"amount":"3.98","currency_code":"USD"}},"rate":0.06,"title":"State Tax"}],"duties":[],"discount_allocations":[{"amount":"3.34","amount_set":{"shop_money":{"amount":"3.34","currency_code":"USD"},"presentment_money":{"amount":"3.34","currency_code":"USD"}},"discount_application_index":0}]}]}],"line_items":[{"id":466157049,"admin_graphql_api_id":"gid://shopify/LineItem/466157049","attributed_staffs":[],"current_quantity":0,"fulfillable_quantity":0,"fulfillment_service":"manual","fulfillment_status":null,"gift_card":false,"grams":200,"name":"IPod Nano - 8gb - green","price":"199.00","price_set":{"shop_money":{"amount":"199.00","currency_code":"USD"},"presentment_money":{"amount":"199.00","currency_code":"USD"}},"product_exists":true,"product_id":632910392,"properties":[{"name":"Custom Engraving Front","value":"Happy Birthday"},{"name":"Custom Engraving Back","value":"Merry Christmas"}],"quantity":1,"requires_shipping":true,"sku":"IPOD2008GREEN","taxable":true,"title":"IPod Nano - 8gb","total_discount":"0.00","total_discount_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"variant_id":39072856,"variant_inventory_management":"shopify","variant_title":"green","vendor":null,"tax_lines":[{"channel_liable":null,"price":"3.98","price_set":{"shop_money":{"amount":"3.98","currency_code":"USD"},"presentment_money":{"amount":"3.98","currency_code":"USD"}},"rate":0.06,"title":"State Tax"}],"duties":[],"discount_allocations":[{"amount":"3.34","amount_set":{"shop_money":{"amount":"3.34","currency_code":"USD"},"presentment_money":{"amount":"3.34","currency_code":"USD"}},"discount_application_index":0}]},{"id":518995019,"admin_graphql_api_id":"gid://shopify/LineItem/518995019","attributed_staffs":[],"current_quantity":1,"fulfillable_quantity":1,"fulfillment_service":"manual","fulfillment_status":null,"gift_card":false,"grams":200,"name":"IPod Nano - 8gb - red","price":"199.00","price_set":{"shop_money":{"amount":"199.00","currency_code":"USD"},"presentment_money":{"amount":"199.00","currency_code":"USD"}},"product_exists":true,"product_id":632910392,"properties":[],"quantity":1,"requires_shipping":true,"sku":"IPOD2008RED","taxable":true,"title":"IPod Nano - 8gb","total_discount":"0.00","total_discount_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"variant_id":49148385,"variant_inventory_management":"shopify","variant_title":"red","vendor":null,"tax_lines":[{"channel_liable":null,"price":"3.98","price_set":{"shop_money":{"amount":"3.98","currency_code":"USD"},"presentment_money":{"amount":"3.98","currency_code":"USD"}},"rate":0.06,"title":"State Tax"}],"duties":[],"discount_allocations":[{"amount":"3.33","amount_set":{"shop_money":{"amount":"3.33","currency_code":"USD"},"presentment_money":{"amount":"3.33","currency_code":"USD"}},"discount_application_index":0}]},{"id":703073504,"admin_graphql_api_id":"gid://shopify/LineItem/703073504","attributed_staffs":[],"current_quantity":0,"fulfillable_quantity":0,"fulfillment_service":"manual","fulfillment_status":null,"gift_card":false,"grams":200,"name":"IPod Nano - 8gb - black","price":"199.00","price_set":{"shop_money":{"amount":"199.00","currency_code":"USD"},"presentment_money":{"amount":"199.00","currency_code":"USD"}},"product_exists":true,"product_id":632910392,"properties":[],"quantity":1,"requires_shipping":true,"sku":"IPOD2008BLACK","taxable":true,"title":"IPod Nano - 8gb","total_discount":"0.00","total_discount_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"variant_id":457924702,"variant_inventory_management":"shopify","variant_title":"black","vendor":null,"tax_lines":[{"channel_liable":null,"price":"3.98","price_set":{"shop_money":{"amount":"3.98","currency_code":"USD"},"presentment_money":{"amount":"3.98","currency_code":"USD"}},"rate":0.06,"title":"State Tax"}],"duties":[],"discount_allocations":[{"amount":"3.33","amount_set":{"shop_money":{"amount":"3.33","currency_code":"USD"},"presentment_money":{"amount":"3.33","currency_code":"USD"}},"discount_application_index":0}]}],"payment_terms":null,"refunds":[{"id":509562969,"admin_graphql_api_id":"gid://shopify/Refund/509562969","created_at":"2025-10-01T15:03:05-04:00","note":"it broke during shipping","order_id":450789469,"processed_at":"2025-10-01T15:03:05-04:00","restock":true,"total_additional_fees_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"total_duties_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"user_id":548380009,"order_adjustments":[],"transactions":[{"id":179259969,"admin_graphql_api_id":"gid://shopify/OrderTransaction/179259969","amount":"209.00","authorization":"authorization-key","created_at":"2005-08-05T12:59:12-04:00","currency":"USD","device_id":null,"error_code":null,"gateway":"bogus","kind":"refund","location_id":null,"message":null,"order_id":450789469,"parent_id":801038806,"payment_id":"#1001.3","processed_at":"2005-08-05T12:59:12-04:00","receipt":{},"source_name":"web","status":"success","test":false,"user_id":null}],"refund_line_items":[{"id":104689539,"line_item_id":703073504,"location_id":487838322,"quantity":1,"restock_type":"legacy_restock","subtotal":195.66,"subtotal_set":{"shop_money":{"amount":"195.66","currency_code":"USD"},"presentment_money":{"amount":"195.66","currency_code":"USD"}},"total_tax":3.98,"total_tax_set":{"shop_money":{"amount":"3.98","currency_code":"USD"},"presentment_money":{"amount":"3.98","currency_code":"USD"}},"line_item":{"id":703073504,"admin_graphql_api_id":"gid://shopify/LineItem/703073504","attributed_staffs":[],"current_quantity":0,"fulfillable_quantity":0,"fulfillment_service":"manual","fulfillment_status":null,"gift_card":false,"grams":200,"name":"IPod Nano - 8gb - black","price":"199.00","price_set":{"shop_money":{"amount":"199.00","currency_code":"USD"},"presentment_money":{"amount":"199.00","currency_code":"USD"}},"product_exists":true,"product_id":632910392,"properties":[],"quantity":1,"requires_shipping":true,"sku":"IPOD2008BLACK","taxable":true,"title":"IPod Nano - 8gb","total_discount":"0.00","total_discount_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"variant_id":457924702,"variant_inventory_management":"shopify","variant_title":"black","vendor":null,"tax_lines":[{"channel_liable":null,"price":"3.98","price_set":{"shop_money":{"amount":"3.98","currency_code":"USD"},"presentment_money":{"amount":"3.98","currency_code":"USD"}},"rate":0.06,"title":"State Tax"}],"duties":[],"discount_allocations":[{"amount":"3.33","amount_set":{"shop_money":{"amount":"3.33","currency_code":"USD"},"presentment_money":{"amount":"3.33","currency_code":"USD"}},"discount_application_index":0}]}},{"id":709875399,"line_item_id":466157049,"location_id":487838322,"quantity":1,"restock_type":"legacy_restock","subtotal":195.67,"subtotal_set":{"shop_money":{"amount":"195.67","currency_code":"USD"},"presentment_money":{"amount":"195.67","currency_code":"USD"}},"total_tax":3.98,"total_tax_set":{"shop_money":{"amount":"3.98","currency_code":"USD"},"presentment_money":{"amount":"3.98","currency_code":"USD"}},"line_item":{"id":466157049,"admin_graphql_api_id":"gid://shopify/LineItem/466157049","attributed_staffs":[],"current_quantity":0,"fulfillable_quantity":0,"fulfillment_service":"manual","fulfillment_status":null,"gift_card":false,"grams":200,"name":"IPod Nano - 8gb - green","price":"199.00","price_set":{"shop_money":{"amount":"199.00","currency_code":"USD"},"presentment_money":{"amount":"199.00","currency_code":"USD"}},"product_exists":true,"product_id":632910392,"properties":[{"name":"Custom Engraving Front","value":"Happy Birthday"},{"name":"Custom Engraving Back","value":"Merry Christmas"}],"quantity":1,"requires_shipping":true,"sku":"IPOD2008GREEN","taxable":true,"title":"IPod Nano - 8gb","total_discount":"0.00","total_discount_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"variant_id":39072856,"variant_inventory_management":"shopify","variant_title":"green","vendor":null,"tax_lines":[{"channel_liable":null,"price":"3.98","price_set":{"shop_money":{"amount":"3.98","currency_code":"USD"},"presentment_money":{"amount":"3.98","currency_code":"USD"}},"rate":0.06,"title":"State Tax"}],"duties":[],"discount_allocations":[{"amount":"3.34","amount_set":{"shop_money":{"amount":"3.34","currency_code":"USD"},"presentment_money":{"amount":"3.34","currency_code":"USD"}},"discount_application_index":0}]}}],"duties":[],"additional_fees":[]}],"shipping_address":{"first_name":"Bob","address1":"Chestnut Street 92","phone":"+1(502)-459-2181","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_lines":[{"id":369256396,"carrier_identifier":null,"code":"Free Shipping","discounted_price":"0.00","discounted_price_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"is_removed":false,"phone":null,"price":"0.00","price_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"requested_fulfillment_service_id":null,"source":"shopify","title":"Free Shipping","tax_lines":[],"discount_allocations":[]}]}]}Retrieve all previous orders from a customer.
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/customers/207119551/orders.json?status=any" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.Customer.orders({ session: session, id: 207119551, status: "any", });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::Customer.orders( session: test_session, id: 207119551, status: "any", )// Session is built by the OAuth process await shopify.rest.Customer.orders({ session: session, id: 207119551, status: "any", });response
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","currency_code":"USD"}},"current_total_additional_fees_set":null,"current_total_discounts":"3.33","current_total_discounts_set":{"shop_money":{"amount":"3.33","currency_code":"USD"},"presentment_money":{"amount":"3.33","currency_code":"USD"}},"current_total_duties_set":null,"current_total_price":"199.65","current_total_price_set":{"shop_money":{"amount":"199.65","currency_code":"USD"},"presentment_money":{"amount":"199.65","currency_code":"USD"}},"current_total_tax":"3.98","current_total_tax_set":{"shop_money":{"amount":"3.98","currency_code":"USD"},"presentment_money":{"amount":"3.98","currency_code":"USD"}},"customer_locale":null,"device_id":null,"discount_codes":[{"code":"TENOFF","amount":"10.00","type":"fixed_amount"}],"duties_included":false,"email":"bob.norman@mail.example.com","estimated_taxes":false,"financial_status":"partially_refunded","fulfillment_status":null,"landing_site":"http://www.example.com?source=abc","landing_site_ref":"abc","location_id":null,"merchant_business_entity_id":"MTU0ODM4MDAwOQ","merchant_of_record_app_id":null,"name":"#1001","note":null,"note_attributes":[{"name":"custom engraving","value":"Happy Birthday"},{"name":"colour","value":"green"}],"number":1,"order_number":1001,"order_status_url":"https://jsmith.myshopify.com/548380009/orders/b1946ac92492d2347c6235b4d2611184/authenticate?key=imasecretipod","original_total_additional_fees_set":null,"original_total_duties_set":null,"payment_gateway_names":["bogus"],"phone":"+557734881234","po_number":"ABC123","presentment_currency":"USD","processed_at":"2008-01-10T11:00:00-05:00","reference":"fhwdgads","referring_site":"http://www.otherexample.com","source_identifier":"fhwdgads","source_name":"web","source_url":null,"subtotal_price":"597.00","subtotal_price_set":{"shop_money":{"amount":"597.00","currency_code":"USD"},"presentment_money":{"amount":"597.00","currency_code":"USD"}},"tags":"","tax_exempt":false,"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"}},"channel_liable":null}],"taxes_included":false,"test":false,"token":"b1946ac92492d2347c6235b4d2611184","total_cash_rounding_payment_adjustment_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"total_cash_rounding_refund_adjustment_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"total_discounts":"10.00","total_discounts_set":{"shop_money":{"amount":"10.00","currency_code":"USD"},"presentment_money":{"amount":"10.00","currency_code":"USD"}},"total_line_items_price":"597.00","total_line_items_price_set":{"shop_money":{"amount":"597.00","currency_code":"USD"},"presentment_money":{"amount":"597.00","currency_code":"USD"}},"total_outstanding":"0.00","total_price":"598.94","total_price_set":{"shop_money":{"amount":"598.94","currency_code":"USD"},"presentment_money":{"amount":"598.94","currency_code":"USD"}},"total_shipping_price_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"total_tax":"11.94","total_tax_set":{"shop_money":{"amount":"11.94","currency_code":"USD"},"presentment_money":{"amount":"11.94","currency_code":"USD"}},"total_tip_received":"0.00","total_weight":0,"updated_at":"2008-01-10T11:00:00-05:00","user_id":null,"billing_address":{"first_name":"Bob","address1":"Chestnut Street 92","phone":"+1(502)-459-2181","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,"created_at":"2025-10-01T15:01:19-04:00","updated_at":"2025-10-01T15:01:19-04:00","first_name":"Bob","last_name":"Norman","state":"disabled","note":null,"verified_email":true,"multipass_identifier":null,"tax_exempt":false,"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"},"tags":"Léon, Noël","email":"bob.norman@mail.example.com","phone":"+16136120707","currency":"USD","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}},"discount_applications":[{"target_type":"line_item","type":"discount_code","value":"10.0","value_type":"fixed_amount","allocation_method":"across","target_selection":"all","code":"TENOFF"}],"fulfillments":[{"id":255858046,"admin_graphql_api_id":"gid://shopify/Fulfillment/255858046","created_at":"2025-10-01T15:01:19-04:00","location_id":655441491,"name":"#1001.0","order_id":450789469,"origin_address":{},"receipt":{"testcase":true,"authorization":"123456"},"service":"manual","shipment_status":null,"status":"failure","tracking_company":"USPS","tracking_number":"1Z1234512345123456","tracking_numbers":["1Z1234512345123456"],"tracking_url":"https://tools.usps.com/go/TrackConfirmAction_input?qtc_tLabels1=1Z1234512345123456","tracking_urls":["https://tools.usps.com/go/TrackConfirmAction_input?qtc_tLabels1=1Z1234512345123456"],"updated_at":"2025-10-01T15:01:19-04:00","line_items":[{"id":466157049,"admin_graphql_api_id":"gid://shopify/LineItem/466157049","attributed_staffs":[],"current_quantity":0,"fulfillable_quantity":0,"fulfillment_service":"manual","fulfillment_status":null,"gift_card":false,"grams":200,"name":"IPod Nano - 8gb - green","price":"199.00","price_set":{"shop_money":{"amount":"199.00","currency_code":"USD"},"presentment_money":{"amount":"199.00","currency_code":"USD"}},"product_exists":true,"product_id":632910392,"properties":[{"name":"Custom Engraving Front","value":"Happy Birthday"},{"name":"Custom Engraving Back","value":"Merry Christmas"}],"quantity":1,"requires_shipping":true,"sku":"IPOD2008GREEN","taxable":true,"title":"IPod Nano - 8gb","total_discount":"0.00","total_discount_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"variant_id":39072856,"variant_inventory_management":"shopify","variant_title":"green","vendor":null,"tax_lines":[{"channel_liable":null,"price":"3.98","price_set":{"shop_money":{"amount":"3.98","currency_code":"USD"},"presentment_money":{"amount":"3.98","currency_code":"USD"}},"rate":0.06,"title":"State Tax"}],"duties":[],"discount_allocations":[{"amount":"3.34","amount_set":{"shop_money":{"amount":"3.34","currency_code":"USD"},"presentment_money":{"amount":"3.34","currency_code":"USD"}},"discount_application_index":0}]}]}],"line_items":[{"id":466157049,"admin_graphql_api_id":"gid://shopify/LineItem/466157049","attributed_staffs":[],"current_quantity":0,"fulfillable_quantity":0,"fulfillment_service":"manual","fulfillment_status":null,"gift_card":false,"grams":200,"name":"IPod Nano - 8gb - green","price":"199.00","price_set":{"shop_money":{"amount":"199.00","currency_code":"USD"},"presentment_money":{"amount":"199.00","currency_code":"USD"}},"product_exists":true,"product_id":632910392,"properties":[{"name":"Custom Engraving Front","value":"Happy Birthday"},{"name":"Custom Engraving Back","value":"Merry Christmas"}],"quantity":1,"requires_shipping":true,"sku":"IPOD2008GREEN","taxable":true,"title":"IPod Nano - 8gb","total_discount":"0.00","total_discount_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"variant_id":39072856,"variant_inventory_management":"shopify","variant_title":"green","vendor":null,"tax_lines":[{"channel_liable":null,"price":"3.98","price_set":{"shop_money":{"amount":"3.98","currency_code":"USD"},"presentment_money":{"amount":"3.98","currency_code":"USD"}},"rate":0.06,"title":"State Tax"}],"duties":[],"discount_allocations":[{"amount":"3.34","amount_set":{"shop_money":{"amount":"3.34","currency_code":"USD"},"presentment_money":{"amount":"3.34","currency_code":"USD"}},"discount_application_index":0}]},{"id":518995019,"admin_graphql_api_id":"gid://shopify/LineItem/518995019","attributed_staffs":[],"current_quantity":1,"fulfillable_quantity":1,"fulfillment_service":"manual","fulfillment_status":null,"gift_card":false,"grams":200,"name":"IPod Nano - 8gb - red","price":"199.00","price_set":{"shop_money":{"amount":"199.00","currency_code":"USD"},"presentment_money":{"amount":"199.00","currency_code":"USD"}},"product_exists":true,"product_id":632910392,"properties":[],"quantity":1,"requires_shipping":true,"sku":"IPOD2008RED","taxable":true,"title":"IPod Nano - 8gb","total_discount":"0.00","total_discount_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"variant_id":49148385,"variant_inventory_management":"shopify","variant_title":"red","vendor":null,"tax_lines":[{"channel_liable":null,"price":"3.98","price_set":{"shop_money":{"amount":"3.98","currency_code":"USD"},"presentment_money":{"amount":"3.98","currency_code":"USD"}},"rate":0.06,"title":"State Tax"}],"duties":[],"discount_allocations":[{"amount":"3.33","amount_set":{"shop_money":{"amount":"3.33","currency_code":"USD"},"presentment_money":{"amount":"3.33","currency_code":"USD"}},"discount_application_index":0}]},{"id":703073504,"admin_graphql_api_id":"gid://shopify/LineItem/703073504","attributed_staffs":[],"current_quantity":0,"fulfillable_quantity":0,"fulfillment_service":"manual","fulfillment_status":null,"gift_card":false,"grams":200,"name":"IPod Nano - 8gb - black","price":"199.00","price_set":{"shop_money":{"amount":"199.00","currency_code":"USD"},"presentment_money":{"amount":"199.00","currency_code":"USD"}},"product_exists":true,"product_id":632910392,"properties":[],"quantity":1,"requires_shipping":true,"sku":"IPOD2008BLACK","taxable":true,"title":"IPod Nano - 8gb","total_discount":"0.00","total_discount_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"variant_id":457924702,"variant_inventory_management":"shopify","variant_title":"black","vendor":null,"tax_lines":[{"channel_liable":null,"price":"3.98","price_set":{"shop_money":{"amount":"3.98","currency_code":"USD"},"presentment_money":{"amount":"3.98","currency_code":"USD"}},"rate":0.06,"title":"State Tax"}],"duties":[],"discount_allocations":[{"amount":"3.33","amount_set":{"shop_money":{"amount":"3.33","currency_code":"USD"},"presentment_money":{"amount":"3.33","currency_code":"USD"}},"discount_application_index":0}]}],"payment_terms":null,"refunds":[{"id":509562969,"admin_graphql_api_id":"gid://shopify/Refund/509562969","created_at":"2025-10-01T15:01:19-04:00","note":"it broke during shipping","order_id":450789469,"processed_at":"2025-10-01T15:01:19-04:00","restock":true,"total_additional_fees_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"total_duties_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"user_id":548380009,"order_adjustments":[],"transactions":[{"id":179259969,"admin_graphql_api_id":"gid://shopify/OrderTransaction/179259969","amount":"209.00","authorization":"authorization-key","created_at":"2005-08-05T12:59:12-04:00","currency":"USD","device_id":null,"error_code":null,"gateway":"bogus","kind":"refund","location_id":null,"message":null,"order_id":450789469,"parent_id":801038806,"payment_id":"#1001.3","processed_at":"2005-08-05T12:59:12-04:00","receipt":{},"source_name":"web","status":"success","test":false,"user_id":null}],"refund_line_items":[{"id":104689539,"line_item_id":703073504,"location_id":487838322,"quantity":1,"restock_type":"legacy_restock","subtotal":195.66,"subtotal_set":{"shop_money":{"amount":"195.66","currency_code":"USD"},"presentment_money":{"amount":"195.66","currency_code":"USD"}},"total_tax":3.98,"total_tax_set":{"shop_money":{"amount":"3.98","currency_code":"USD"},"presentment_money":{"amount":"3.98","currency_code":"USD"}},"line_item":{"id":703073504,"admin_graphql_api_id":"gid://shopify/LineItem/703073504","attributed_staffs":[],"current_quantity":0,"fulfillable_quantity":0,"fulfillment_service":"manual","fulfillment_status":null,"gift_card":false,"grams":200,"name":"IPod Nano - 8gb - black","price":"199.00","price_set":{"shop_money":{"amount":"199.00","currency_code":"USD"},"presentment_money":{"amount":"199.00","currency_code":"USD"}},"product_exists":true,"product_id":632910392,"properties":[],"quantity":1,"requires_shipping":true,"sku":"IPOD2008BLACK","taxable":true,"title":"IPod Nano - 8gb","total_discount":"0.00","total_discount_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"variant_id":457924702,"variant_inventory_management":"shopify","variant_title":"black","vendor":null,"tax_lines":[{"channel_liable":null,"price":"3.98","price_set":{"shop_money":{"amount":"3.98","currency_code":"USD"},"presentment_money":{"amount":"3.98","currency_code":"USD"}},"rate":0.06,"title":"State Tax"}],"duties":[],"discount_allocations":[{"amount":"3.33","amount_set":{"shop_money":{"amount":"3.33","currency_code":"USD"},"presentment_money":{"amount":"3.33","currency_code":"USD"}},"discount_application_index":0}]}},{"id":709875399,"line_item_id":466157049,"location_id":487838322,"quantity":1,"restock_type":"legacy_restock","subtotal":195.67,"subtotal_set":{"shop_money":{"amount":"195.67","currency_code":"USD"},"presentment_money":{"amount":"195.67","currency_code":"USD"}},"total_tax":3.98,"total_tax_set":{"shop_money":{"amount":"3.98","currency_code":"USD"},"presentment_money":{"amount":"3.98","currency_code":"USD"}},"line_item":{"id":466157049,"admin_graphql_api_id":"gid://shopify/LineItem/466157049","attributed_staffs":[],"current_quantity":0,"fulfillable_quantity":0,"fulfillment_service":"manual","fulfillment_status":null,"gift_card":false,"grams":200,"name":"IPod Nano - 8gb - green","price":"199.00","price_set":{"shop_money":{"amount":"199.00","currency_code":"USD"},"presentment_money":{"amount":"199.00","currency_code":"USD"}},"product_exists":true,"product_id":632910392,"properties":[{"name":"Custom Engraving Front","value":"Happy Birthday"},{"name":"Custom Engraving Back","value":"Merry Christmas"}],"quantity":1,"requires_shipping":true,"sku":"IPOD2008GREEN","taxable":true,"title":"IPod Nano - 8gb","total_discount":"0.00","total_discount_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"variant_id":39072856,"variant_inventory_management":"shopify","variant_title":"green","vendor":null,"tax_lines":[{"channel_liable":null,"price":"3.98","price_set":{"shop_money":{"amount":"3.98","currency_code":"USD"},"presentment_money":{"amount":"3.98","currency_code":"USD"}},"rate":0.06,"title":"State Tax"}],"duties":[],"discount_allocations":[{"amount":"3.34","amount_set":{"shop_money":{"amount":"3.34","currency_code":"USD"},"presentment_money":{"amount":"3.34","currency_code":"USD"}},"discount_application_index":0}]}}],"duties":[],"additional_fees":[]}],"shipping_address":{"first_name":"Bob","address1":"Chestnut Street 92","phone":"+1(502)-459-2181","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_lines":[{"id":369256396,"carrier_identifier":null,"code":"Free Shipping","discounted_price":"0.00","discounted_price_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"is_removed":false,"phone":null,"price":"0.00","price_set":{"shop_money":{"amount":"0.00","currency_code":"USD"},"presentment_money":{"amount":"0.00","currency_code":"USD"}},"requested_fulfillment_service_id":null,"source":"shopify","title":"Free Shipping","tax_lines":[],"discount_allocations":[]}]}]}
Anchor to GET request, Retrieves a count of customersgetRetrieves a count of customers
get
Retrieves a count of customers
Requires
customers access scope.Retrieves a count of all customers.
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?
Retrieve a count of all customers tag:elasticsearch:true
Retrieve a count of all customers tag:elasticsearch:true
Retrieve a count of customers changed after a specified date tag:elasticsearch:true
Retrieve a count of customers changed after a specified date tag:elasticsearch:true
Query parameters
updated_
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 tag:elasticsearch:true
Retrieve a count of customers created after a specified date tag:elasticsearch:true
Query parameters
created_
Count customers created after a specified date.
(format: 2014-04-25T16:15:47-04:00)
Was this section helpful?
get
/admin/api/2025-10/customers/count.
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/customers/count.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}
Response
JSON
HTTP/1.1 200 OK
{
"count": 3
}
examples
Retrieve a count of all customers tag:elasticsearch:true
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/customers/count.json" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.Customer.count({ session: session, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::Customer.count( session: test_session, )// Session is built by the OAuth process await shopify.rest.Customer.count({ session: session, });response
HTTP/1.1 200 OK{"count":3}Retrieve a count of customers changed after a specified date tag:elasticsearch:true
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/customers/count.json?updated_at_min=2025-09-30+19%3A02%3A56" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.Customer.count({ session: session, updated_at_min: "2025-09-30 19:02:56", });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::Customer.count( session: test_session, updated_at_min: "2025-09-30 19:02:56", )// Session is built by the OAuth process await shopify.rest.Customer.count({ session: session, updated_at_min: "2025-09-30 19:02:56", });response
HTTP/1.1 200 OK{"count":3}Retrieve a count of customers created after a specified date tag:elasticsearch:true
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/customers/count.json?created_at_min=2025-09-30+19%3A01%3A53" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.Customer.count({ session: session, created_at_min: "2025-09-30 19:01:53", });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::Customer.count( session: test_session, created_at_min: "2025-09-30 19:01:53", )// Session is built by the OAuth process await shopify.rest.Customer.count({ session: session, created_at_min: "2025-09-30 19:01:53", });response
HTTP/1.1 200 OK{"count":3}
Anchor to GET request, Searches for customers that match a supplied querygetSearches for customers that match a supplied query
get
Searches for customers that match a supplied query
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.
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?
Search for a customer with a specified email address tag:elasticsearch:true
Search for a customer with a specified email address tag:elasticsearch:true
Query parameters
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.
Search for all customers with a specified last name and show certain fields tag:elasticsearch:true
Search for all customers with a specified last name and show certain fields tag:elasticsearch:true
Query parameters
fields=
Show only certain fields, specified by a comma-separated list of field names.
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.
Search for all customers with a specified tag and show only certain fields tag:elasticsearch:true
Search for all customers with a specified tag and show only certain fields tag:elasticsearch:true
Query parameters
fields=
Show only certain fields, specified by a comma-separated list of field names.
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.
Search for all customers with an address in the United States and a specified first name tag:elasticsearch:true
Search for all customers with an address in the United States and a specified first name tag:elasticsearch:true
Query parameters
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.
Search for customers matching a specified email domain tag:elasticsearch:true
Search for customers matching a specified email domain tag:elasticsearch:true
Query parameters
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.
Search for customers who have verified their email address and show only certain fields tag:elasticsearch:true
Search for customers who have verified their email address and show only certain fields tag:elasticsearch:true
Query parameters
fields=
Show only certain fields, specified by a comma-separated list of field names.
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?
get
/admin/api/2025-10/customers/search.
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/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,
"created_at": "2025-10-01T15:03:38-04:00",
"updated_at": "2025-10-01T15:03:38-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",
"email": "bob.norman@mail.example.com",
"phone": "+16136120707",
"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
}
],
"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
}
}
]
}
examples
Search for a customer with a specified email address tag:elasticsearch:true
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/customers/search.json?query=email%3Abob.norman%40mail.example.com" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.Customer.search({ session: session, query: "email:bob.norman@mail.example.com", });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::Customer.search( session: test_session, query: "email:bob.norman@mail.example.com", )// Session is built by the OAuth process await shopify.rest.Customer.search({ session: session, query: "email:bob.norman@mail.example.com", });response
HTTP/1.1 200 OK{"customers":[{"id":207119551,"created_at":"2025-10-01T15:03:38-04:00","updated_at":"2025-10-01T15:03:38-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","email":"bob.norman@mail.example.com","phone":"+16136120707","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}],"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}}]}Search for all customers with a specified last name and show certain fields tag:elasticsearch:true
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/customers/search.json?fields=id%2C+email%2C+first_name%2C+last_name&query=last_name%3ANorman" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.Customer.search({ session: session, fields: "id, email, first_name, last_name", query: "last_name:Norman", });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::Customer.search( session: test_session, fields: "id, email, first_name, last_name", query: "last_name:Norman", )// Session is built by the OAuth process await shopify.rest.Customer.search({ session: session, fields: "id, email, first_name, last_name", query: "last_name:Norman", });response
HTTP/1.1 200 OK{"customers":[{"id":207119551,"first_name":"Bob","last_name":"Norman","email":"bob.norman@mail.example.com"}]}Search for all customers with a specified tag and show only certain fields tag:elasticsearch:true
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/customers/search.json?fields=id%2C+email%2C+first_name%2C+last_name%2C+tags&query=customer_tag%3ANew+Customer" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.Customer.search({ session: session, fields: "id, email, first_name, last_name, tags", query: "customer_tag:New Customer", });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::Customer.search( session: test_session, fields: "id, email, first_name, last_name, tags", query: "customer_tag:New Customer", )// Session is built by the OAuth process await shopify.rest.Customer.search({ session: session, fields: "id, email, first_name, last_name, tags", query: "customer_tag:New Customer", });response
HTTP/1.1 200 OK{"customers":[{"id":1073339480,"first_name":"Isabella","last_name":"Garcia","tags":"New Customer","email":"isabella.garcia@example.com"}]}Search for all customers with an address in the United States and a specified first name tag:elasticsearch:true
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/customers/search.json?query=first_name%3ABob+country%3AUnited+States" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.Customer.search({ session: session, query: "first_name:Bob country:United States", });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::Customer.search( session: test_session, query: "first_name:Bob country:United States", )// Session is built by the OAuth process await shopify.rest.Customer.search({ session: session, query: "first_name:Bob country:United States", });response
HTTP/1.1 200 OK{"customers":[{"id":207119551,"created_at":"2025-10-01T15:02:57-04:00","updated_at":"2025-10-01T15:02:57-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","email":"bob.norman@mail.example.com","phone":"+16136120707","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}],"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}}]}Search for customers matching a specified email domain tag:elasticsearch:true
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/customers/search.json?query=email%3A%2A%40mail.example.com" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.Customer.search({ session: session, query: "email:*@mail.example.com", });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::Customer.search( session: test_session, query: "email:*@mail.example.com", )// Session is built by the OAuth process await shopify.rest.Customer.search({ session: session, query: "email:*@mail.example.com", });response
HTTP/1.1 200 OK{"customers":[{"id":207119551,"created_at":"2025-10-01T15:03:22-04:00","updated_at":"2025-10-01T15:03:22-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","email":"bob.norman@mail.example.com","phone":"+16136120707","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}],"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}}]}Search for customers who have verified their email address and show only certain fields tag:elasticsearch:true
curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/customers/search.json?fields=id%2C+email%2C+first_name%2C+last_name%2C+verified_email&query=verified_email%3Atrue" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.Customer.search({ session: session, fields: "id, email, first_name, last_name, verified_email", query: "verified_email:true", });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::Customer.search( session: test_session, fields: "id, email, first_name, last_name, verified_email", query: "verified_email:true", )// Session is built by the OAuth process await shopify.rest.Customer.search({ session: session, fields: "id, email, first_name, last_name, verified_email", query: "verified_email:true", });response
HTTP/1.1 200 OK{"customers":[{"id":1073339475,"first_name":"Isabella","last_name":"Garcia","verified_email":true,"email":"isabella.garcia@example.com"},{"id":207119551,"first_name":"Bob","last_name":"Norman","verified_email":true,"email":"bob.norman@mail.example.com"}]}
Anchor to PUT request, Updates a customerputUpdates a customer
put
Updates a customer
Requires
customers access scope.Updates a customer.
api_version
string
required
customer_id
string
required
Was this section helpful?
Add metafield to an existing customer
Add metafield to an existing customer
Update a customer's tags
Update a customer's tags
Path parameters
customer_
string
required
Request body
Show customer properties
Show customer properties
customer.id:
A unique identifier for the customer.
customer.tags:
->
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
Update details for a customer
Path parameters
customer_
string
required
Request body
Show customer properties
Show customer properties
Updating a customer that doesn't exist returns an error
Updating a customer that doesn't exist returns an error
Path parameters
customer_
string
required
Request body
Show customer properties
Show customer properties
customer.id:
A unique identifier for the customer.
customer.tags:
->
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-10/customers/207119551.
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-10/customers/207119551.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}
Response
JSON
HTTP/1.1 200 OK
{
"customer": {
"first_name": "Bob",
"last_name": "Norman",
"id": 207119551,
"created_at": "2025-10-01T15:00:56-04:00",
"updated_at": "2025-10-01T15:00:56-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",
"email": "bob.norman@mail.example.com",
"phone": "+16136120707",
"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
}
],
"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
}
}
}
examples
Add metafield to an existing customer
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-10/customers/207119551.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json"const { admin, session } = await authenticate.admin(request); const customer = new admin.rest.resources.Customer({session: session}); customer.id = 207119551; customer.metafields = [ { "key": "new", "value": "newvalue", "type": "single_line_text_field", "namespace": "global" } ]; await customer.save({ update: true, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session customer = ShopifyAPI::Customer.new(session: test_session) customer.id = 207119551 customer.metafields = [ { "key" => "new", "value" => "newvalue", "type" => "single_line_text_field", "namespace" => "global" } ] customer.save!// Session is built by the OAuth process const customer = new shopify.rest.Customer({session: session}); customer.id = 207119551; customer.metafields = [ { "key": "new", "value": "newvalue", "type": "single_line_text_field", "namespace": "global" } ]; await customer.save({ update: true, });response
HTTP/1.1 200 OK{"customer":{"first_name":"Bob","last_name":"Norman","id":207119551,"created_at":"2025-10-01T15:00:56-04:00","updated_at":"2025-10-01T15:00:56-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","email":"bob.norman@mail.example.com","phone":"+16136120707","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}],"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}}}Update a customer's tags
curl -d '{"customer":{"id":207119551,"tags":"New Customer, Repeat Customer"}}' \ -X PUT "https://your-development-store.myshopify.com/admin/api/2025-10/customers/207119551.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json"const { admin, session } = await authenticate.admin(request); const customer = new admin.rest.resources.Customer({session: session}); customer.id = 207119551; customer.tags = "New Customer, Repeat Customer"; await customer.save({ update: true, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session customer = ShopifyAPI::Customer.new(session: test_session) customer.id = 207119551 customer.tags = "New Customer, Repeat Customer" customer.save!// Session is built by the OAuth process const customer = new shopify.rest.Customer({session: session}); customer.id = 207119551; customer.tags = "New Customer, Repeat Customer"; await customer.save({ update: true, });response
HTTP/1.1 200 OK{"customer":{"first_name":"Bob","last_name":"Norman","id":207119551,"created_at":"2025-10-01T15:02:09-04:00","updated_at":"2025-10-01T15:02:16-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":"New Customer, Repeat Customer","last_order_name":"#1001","email":"bob.norman@mail.example.com","phone":"+16136120707","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}],"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}}}Update details for a customer
curl -d '{"customer":{"id":207119551,"email":"changed@example.com","note":"Customer is a great guy"}}' \ -X PUT "https://your-development-store.myshopify.com/admin/api/2025-10/customers/207119551.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json"const { admin, session } = await authenticate.admin(request); const customer = new admin.rest.resources.Customer({session: session}); customer.id = 207119551; customer.email = "changed@example.com"; customer.note = "Customer is a great guy"; await customer.save({ update: true, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session customer = ShopifyAPI::Customer.new(session: test_session) customer.id = 207119551 customer.email = "changed@example.com" customer.note = "Customer is a great guy" customer.save!// Session is built by the OAuth process const customer = new shopify.rest.Customer({session: session}); customer.id = 207119551; customer.email = "changed@example.com"; customer.note = "Customer is a great guy"; await customer.save({ update: true, });response
HTTP/1.1 200 OK{"customer":{"first_name":"Bob","last_name":"Norman","note":"Customer is a great guy","id":207119551,"created_at":"2025-10-01T15:02:01-04:00","updated_at":"2025-10-01T15:02:09-04:00","orders_count":1,"state":"disabled","total_spent":"199.65","last_order_id":450789469,"verified_email":true,"multipass_identifier":null,"tax_exempt":false,"tags":"Léon, Noël","last_order_name":"#1001","email":"changed@example.com","phone":"+16136120707","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}],"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":"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}}}Updating a customer that doesn't exist returns an error
curl -d '{"customer":{"id":123,"tags":"New Customer, Repeat Customer"}}' \ -X PUT "https://your-development-store.myshopify.com/admin/api/2025-10/customers/123.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json"const { admin, session } = await authenticate.admin(request); const customer = new admin.rest.resources.Customer({session: session}); customer.id = 123; customer.tags = "New Customer, Repeat Customer"; await customer.save({ update: true, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session customer = ShopifyAPI::Customer.new(session: test_session) customer.id = 123 customer.tags = "New Customer, Repeat Customer" customer.save!// Session is built by the OAuth process const customer = new shopify.rest.Customer({session: session}); customer.id = 123; customer.tags = "New Customer, Repeat Customer"; await customer.save({ update: true, });response
HTTP/1.1 404 Not Found{"errors":"Not Found"}
Anchor to DELETE request, Deletes a customerdelDeletes a customer
del
Deletes a customer
Requires
customers access scope.Deletes a customer. A customer can't be deleted if they have existing orders.
api_version
string
required
customer_id
string
required
Was this section helpful?
Remove an existing customer
Remove an existing customer
Path parameters
customer_
string
required
Was this section helpful?
del
/admin/api/2025-10/customers/207119551.
curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2025-10/customers/207119551.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}
Response
JSON
HTTP/1.1 200 OK
{}
examples
Remove an existing customer
curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2025-10/customers/207119551.json" \ -H "X-Shopify-Access-Token: {access_token}"await admin.rest.resources.Customer.delete({ session: session, id: 207119551, });# Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::Customer.delete( session: test_session, id: 207119551, )// Session is built by the OAuth process await shopify.rest.Customer.delete({ session: session, id: 207119551, });response
HTTP/1.1 200 OK{}