Customer
Private Customer API endpoints
An API endpoint to get list of customers. Results are always ordered by customer ID, newest first.
Query parameters
pageoptionalintegerPage number
per_pageoptionalintegerItems per page
idsoptionalinteger[]Filter by customer IDs
emailsoptionalstring[]Keep only customers with one of these email addresses. Each match is exact, not a partial search, and ignores letter case.
has_active_subscriptionoptionalinteger1 keeps only customers with at least one active subscription, 0 keeps only customers without any active subscription. Send 1 or 0, not true/false.
Possible values: 0, 1.
tagsoptionalinteger[]Keep only customers tagged with at least one of these tag IDs. Every ID must be a tag of your shop.
countryoptionalstringKeep only customers with an address in this country. The value is the country name (for example United States), not a country code, and must match a known shipping country.
orders_countoptionalintegerKeep only customers whose total order count equals this number exactly.
balanceoptionalobjectFilter on the customer's store credit balance, in minor units. Both keys are required as soon as balance is sent. Customers with no balance record are treated as 0 and are matched whenever the comparison holds for zero.
expand[]optionalstring[]List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.
Returnsobject
Customers list response
Error responses
422objectOne or more query parameters failed validation, for example a malformed emails entry, a tag ID that does not belong to the shop, an unknown country name, or a balance filter missing its value or operator.
Create a customer in your shop. When a user account already exists for the email it is reused and only the shop customer record is created, so first_name and last_name are ignored in that case; otherwise a new user account is registered with those names. The email must not already belong to a customer of this shop.
Query parameters
expand[]optionalstring[]List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.
Request body
emailRequiredstringMust not already belong to a customer of this shop. When a user account with this email already exists (for example because the person is a customer of another shop) that account is reused and first_name/last_name are ignored.
Format: email.
first_nameRequiredstringlast_nameRequiredstringmarketing_consentoptionalintegerMarketing opt-in. Send 1 or 0 (JSON true is coerced to 1; false is rejected). Defaults to 0 when omitted.
Possible values: 0, 1.
external_idoptionalstring | nullYour own identifier for this customer.
ReturnsCustomer
Customer object response
Error responses
422objectValidation failed, for example the email already belongs to a customer of this shop, or a required name is missing or longer than 50 characters.
A detailed description of the customer.
Path parameters
customer_idRequiredintegerCustomer ID
Format: integer.
Query parameters
expand[]optionalstring[]List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.
ReturnsCustomer
Customer object response
Error responses
404objectThe customer does not exist or belongs to another shop.
Partially update a customer. Only the keys present in the body are applied, every other field is left untouched. marketing_consent and tos_consent are grant-only - once either is granted, sending it again (with any value) is rejected with a validation error - and default_payment_method_id must reference a payment method of this customer.
Path parameters
customer_idRequiredintegerCustomer ID
Format: integer.
Query parameters
expand[]optionalstring[]List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.
Request body
marketing_consentoptionalintegerMarketing opt-in, grant-only. Send 1 or 0 (JSON true is coerced to 1; false is rejected). 1 records the opt-in. Once it is granted the field can no longer be sent at all - any further marketing_consent in the body, 1 or 0, is rejected with a validation error (422). While it is still ungranted, 0 stores an explicit refusal (marketing_consent: false). It is independent of tos_consent; neither one requires the other.
Possible values: 0, 1.
tos_consentoptionalintegerTerms-of-service consent, grant-only. Send 1 or 0, not true/false. 1 requires tos_consent_at and stores that date as the consent date. Once tos_consent_at is set the field can no longer be sent at all - any further tos_consent in the body, 1 or 0, is rejected with a validation error (422), so an existing consent date is never overwritten and consent cannot be withdrawn. While it is still unset, 0 is accepted and does nothing.
Possible values: 0, 1.
tos_consent_atoptionalstringThe date and time the customer accepted the terms of service. Required when tos_consent is 1 and not accepted otherwise. Any parsable date is accepted and the value is normalised to UTC before it is stored.
Format: date-time.
default_payment_method_idoptionalinteger | nullMust be a payment method belonging to this customer. null clears the default.
tagsoptionalobjectTag changes to apply to the customer.
metadataoptionalMetadataUpdateCustomer metadata.
ReturnsCustomer
Customer object response
Error responses
404objectThe customer does not exist or belongs to another shop.
422objectValidation failed, for example a default_payment_method_id that is not a payment method of this customer, a tags.delete ID that is not a tag of this shop, a duplicated tags.create value, or an invalid metadata entry.
Permanently delete the customer and return its last state. Abandoned cart tracking for the email is cleared, and the underlying user account is deleted as well when this was their only customer record and they are not a merchant, which also removes the account's addresses and pickup info. Stored payment methods and store credit balance rows are left untouched. The endpoint is only available while GDPR handling is enabled for the shop.
Path parameters
customer_idRequiredintegerCustomer ID
Format: integer.
Query parameters
expand[]optionalstring[]List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.
ReturnsCustomer
The deleted customer object, serialised as it was just before deletion.
Error responses
400objectGDPR handling is disabled for the shop.
404objectThe customer does not exist or belongs to another shop.
Add or remove store credit and return the customer with the updated balance. amount is signed: positive credits the balance, negative debits it. A debit that would take the balance below 0 is rejected with insufficient_balance and nothing changes. Every change is recorded in the customer's balance history and flagged as made by the shop owner.
Path parameters
customer_idRequiredintegerCustomer ID
Format: integer.
Query parameters
expand[]optionalstring[]List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.
Request body
amountRequiredintegerSigned change to the customer's store credit balance, in minor units. Positive credits, negative debits, 0 is rejected.
ReturnsCustomer
Customer object response, with the updated balance
Error responses
400objectThe debit is larger than the customer's current balance, or the customer has no balance yet. Nothing is changed.
404objectThe customer does not exist or belongs to another shop.
422objectValidation failed, for example amount is missing, is not an integer, is 0, or is outside -9999999 to 9999999.
Add an internal note to the customer. Notes are only visible through the private API. Returns the customer object with notes expanded, plus any expand[] requested.
Path parameters
customer_idRequiredintegerCustomer ID
Format: integer.
Query parameters
expand[]optionalstring[]List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.
Request body
noteRequiredstringNote body.
ReturnsCustomer
The customer object with notes included.
Error responses
404objectThe customer does not exist or belongs to another shop.
422objectValidation failed, for example note is missing or longer than 65535 characters.
Replace the body of a note. The note must belong to the customer in the path. Returns the customer object with notes expanded, plus any expand[] requested.
Path parameters
customer_idRequiredintegerCustomer ID
Format: integer.
note_idRequiredintegerNote ID
Format: integer.
Query parameters
expand[]optionalstring[]List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.
Request body
noteRequiredstringNote body.
ReturnsCustomer
The customer object with notes included.
Error responses
404objectThe customer or the note does not exist, the customer belongs to another shop, or the note belongs to another customer.
422objectValidation failed, for example note is missing or longer than 65535 characters.
Permanently delete a note and return the customer it belonged to, with notes expanded (null once the last note is gone) plus any expand[] requested. The note must belong to the customer in the path.
Path parameters
customer_idRequiredintegerCustomer ID
Format: integer.
note_idRequiredintegerNote ID
Format: integer.
Query parameters
expand[]optionalstring[]List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.
ReturnsCustomer
The customer object with notes included.
Error responses
404objectThe customer or the note does not exist, the customer belongs to another shop, or the note belongs to another customer.