Customer
Private Customer API endpoints
- GET/customers
- POST/customers
- GET/customers/{customer_id}
- PATCH/customers/{customer_id}
- DELETE/customers/{customer_id}
- POST/customers/{customer_id}/balance
- POST/customers/{customer_id}/notes
- PATCH/customers/{customer_id}/notes/{note_id}
- DELETE/customers/{customer_id}/notes/{note_id}
- POST/customers/{customer_id}/addresses
- PATCH/customers/{customer_id}/addresses/{address_id}
- DELETE/customers/{customer_id}/addresses/{address_id}
- GET/customers/{customer_id}/pickup_info
- POST/customers/{customer_id}/pickup_info
- PATCH/customers/{customer_id}/pickup_info/{pickup_info_id}
- DELETE/customers/{customer_id}/pickup_info/{pickup_info_id}
- POST/customers/{customer_id}/payment_methods
- DELETE/customers/{customer_id}/payment_methods/{payment_method_id}
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
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. metadata, tags, tags_meta, balance and past_due_invoice_count are always present and do not need to be requested. Available keys: default_payment_method, payment_methods, subscriptions, notes, addresses. Nested keys are accepted too, e.g. subscriptions.items.
Returnsobject
Customers list response
Error responses
422objectOne or more query parameters failed validation, for example 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. metadata, tags, tags_meta, balance and past_due_invoice_count are always present and do not need to be requested. Available keys: default_payment_method, payment_methods, subscriptions, notes, addresses. Nested keys are accepted too, e.g. subscriptions.items.
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, not true/false. 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. metadata, tags, tags_meta, balance and past_due_invoice_count are always present and do not need to be requested. Available keys: default_payment_method, payment_methods, subscriptions, notes, addresses. Nested keys are accepted too, e.g. subscriptions.items.
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. metadata, tags, tags_meta, balance and past_due_invoice_count are always present and do not need to be requested. Available keys: default_payment_method, payment_methods, subscriptions, notes, addresses. Nested keys are accepted too, e.g. subscriptions.items.
Request body
marketing_consentoptionalintegerMarketing opt-in, grant-only. Send 1 or 0, not true/false. 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 is accepted and does nothing. 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.
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, or a duplicated tags.create value.
Permanently delete the customer. 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. Stored payment methods are left untouched. The endpoint is only available while GDPR handling is enabled for the shop.
Path parameters
customer_idRequiredintegerCustomer ID
Format: integer.
ReturnsDeletedObject
The customer was deleted.
Error responses
400objectGDPR handling is disabled for the shop.
404objectThe customer does not exist or belongs to another shop.
Add store credit to the customer's balance and return the customer with the updated balance. Credits only - amount cannot be negative, so this endpoint can never lower a balance. 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. metadata, tags, tags_meta, balance and past_due_invoice_count are always present and do not need to be requested. Available keys: default_payment_method, payment_methods, subscriptions, notes, addresses. Nested keys are accepted too, e.g. subscriptions.items.
Request body
amountRequiredintegerAmount added to the customer's store credit balance, in minor units.
ReturnsCustomer
Customer object response, with the updated balance
Error responses
404objectThe customer does not exist or belongs to another shop.
422objectValidation failed, for example amount is missing, is not an integer, is negative, or is above 9999999.
Add an internal note to the customer. Notes are only visible through the private API.
Path parameters
customer_idRequiredintegerCustomer ID
Format: integer.
Request body
noteRequiredstringNote body.
ReturnsNote
Note object response
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.
Path parameters
customer_idRequiredintegerCustomer ID
Format: integer.
note_idRequiredintegerNote ID
Format: integer.
Request body
noteRequiredstringNote body.
ReturnsNote
Note object response
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. The note must belong to the customer in the path.
Path parameters
customer_idRequiredintegerCustomer ID
Format: integer.
note_idRequiredintegerNote ID
Format: integer.
ReturnsDeletedObject
The note was deleted.
Error responses
404objectThe customer or the note does not exist, the customer belongs to another shop, or the note belongs to another customer.
Add a delivery address to the customer. Whether region or region_id is required depends on the country: countries that have regions require region_id and reject region, countries without regions require region and reject region_id. When neither is sent, the API tries to derive the region from the country and zip before validating.
Path parameters
customer_idRequiredintegerCustomer ID
Format: integer.
Request body
first_nameRequiredstringlast_nameRequiredstringphoneoptionalstring | nullRequired unless the shop has optional phone numbers enabled. Must be a valid international phone number.
company_nameoptionalstring | nulladdress_oneRequiredstringaddress_twooptionalstring | nullcityRequiredstringzipRequiredstringcountry_idRequiredintegerID of a known shipping country.
region_idoptionalintegerRequired when the country has regions, and prohibited when it has none. Must be a region of country_id. When neither region_id nor region is sent, the API first tries to derive the region from the country code and zip.
regionoptionalstringFree-text region, required when the country has no regions and prohibited when it has them. When neither region nor region_id is sent, the API first tries to derive the region from the country code and zip.
ReturnsAddress
Address object response
Error responses
404objectThe customer does not exist or belongs to another shop.
422objectValidation failed, for example an unknown country_id, a region_id that does not belong to that country, a region/region_id combination that does not match the country, an invalid phone number, or a zip outside 3-16 characters.
Update a customer address. All required fields must be sent again, but optional fields (company_name, address_two, and phone when the shop makes it optional) are merged: leaving one out keeps its current value, and sending it as an explicit null clears it. The address must belong to the customer in the path.
Path parameters
customer_idRequiredintegerCustomer ID
Format: integer.
address_idRequiredintegerAddress ID
Format: integer.
Request body
first_nameRequiredstringlast_nameRequiredstringphoneoptionalstring | nullRequired unless the shop has optional phone numbers enabled. Must be a valid international phone number.
company_nameoptionalstring | nulladdress_oneRequiredstringaddress_twooptionalstring | nullcityRequiredstringzipRequiredstringcountry_idRequiredintegerID of a known shipping country.
region_idoptionalintegerRequired when the country has regions, and prohibited when it has none. Must be a region of country_id. When neither region_id nor region is sent, the API first tries to derive the region from the country code and zip.
regionoptionalstringFree-text region, required when the country has no regions and prohibited when it has them. When neither region nor region_id is sent, the API first tries to derive the region from the country code and zip.
ReturnsAddress
Address object response
Error responses
404objectThe customer or the address does not exist, the customer belongs to another shop, or the address belongs to another customer.
422objectValidation failed, for example an unknown country_id, a region_id that does not belong to that country, a region/region_id combination that does not match the country, an invalid phone number, or a zip outside 3-16 characters.
Delete a customer address. An address that is still linked to a subscription, or to an order awaiting delivery or a future shipment, cannot be deleted.
Path parameters
customer_idRequiredintegerCustomer ID
Format: integer.
address_idRequiredintegerAddress ID
Format: integer.
ReturnsAddress
The deleted address
Error responses
404objectThe customer or the address does not exist, the customer belongs to another shop, or the address belongs to another customer.
422objectThe address is in use: it is the shipping or billing address of a subscription, or the shipping address of an order awaiting delivery or a future shipment.
List the customer's local pickup contacts. Without shipping_method_id, and for a pickup-point shipping method, only entries with no linked pickup point are returned. For a custom local pickup method, only entries whose pickup point is in that method's country are returned. The response is not paginated.
Path parameters
customer_idRequiredintegerCustomer ID
Format: integer.
Query parameters
shipping_method_idoptionalinteger | nullA published local pickup shipping method of your shop, used to narrow the list.
Returnsobject
Customer pickup info list response
Error responses
404objectThe customer does not exist or belongs to another shop.
422objectshipping_method_id is not a published local pickup method of this shop.
Add a local pickup contact to the customer. Sending pickup_point_id together with pickup_point_type links an external pickup point, which is looked up at the provider and must sit in a country covered by one of the shop's published local pickup methods. Omit both to store a plain pickup contact.
Path parameters
customer_idRequiredintegerCustomer ID
Format: integer.
Request body
first_nameRequiredstringlast_nameRequiredstringphoneoptionalstring | nullRequired unless the shop has optional phone numbers enabled. Must be a valid international phone number.
pickup_point_idoptionalstringExternal pickup point reference, prefixed with the ISO country code. Required as soon as pickup_point_type is sent. The country must be covered by one of the shop's published local pickup methods and the point must exist at the provider.
pickup_point_typeoptionalstringRequired as soon as pickup_point_id is sent.
Possible values: mondial_relay.
ReturnsCustomerPickupInfo
Customer pickup info object response
Error responses
404objectThe customer does not exist or belongs to another shop.
422objectValidation failed, for example a missing name, an invalid phone number, a pickup_point_id that does not match the CC-123456 format or is unknown at the provider, or only one of pickup_point_id/pickup_point_type being sent.
Update the contact details of a local pickup entry. Only the name and phone number can be changed; the linked pickup point is fixed at creation time. Unlike a customer address, this payload is not merged - a phone left out is cleared when the shop makes phone numbers optional. The entry must belong to the customer in the path.
Path parameters
customer_idRequiredintegerCustomer ID
Format: integer.
pickup_info_idRequiredintegerPickup info ID
Format: integer.
Request body
first_nameRequiredstringlast_nameRequiredstringphoneoptionalstring | nullRequired unless the shop has optional phone numbers enabled. Must be a valid international phone number.
ReturnsCustomerPickupInfo
Customer pickup info object response
Error responses
404objectThe customer or the pickup info does not exist, the customer belongs to another shop, or the pickup info belongs to another customer.
422objectValidation failed, for example a missing first_name/last_name or an invalid phone number.
Delete a local pickup entry. An entry that is still linked to a subscription, or to an order awaiting delivery or a future shipment, cannot be deleted.
Path parameters
customer_idRequiredintegerCustomer ID
Format: integer.
pickup_info_idRequiredintegerPickup info ID
Format: integer.
ReturnsCustomerPickupInfo
The deleted pickup info
Error responses
404objectThe customer or the pickup info does not exist, the customer belongs to another shop, or the pickup info belongs to another customer.
422objectThe pickup info is in use: it is the shipping address of a subscription, or of an order awaiting delivery or a future shipment.
Store a payment method for the customer from a gateway-side token. The token is exchanged with the gateway; only the shape of token is validated up front, so a token the gateway rejects surfaces as a server error rather than a validation error.
Path parameters
customer_idRequiredintegerCustomer ID
Format: integer.
Request body
gateway_idRequiredintegerID of a payment gateway belonging to your shop.
tokenRequiredstringGateway-side token for the payment instrument, for example a Stripe payment method ID or a Braintree nonce. It is exchanged with the gateway on the spot.
ReturnsPaymentMethod
Payment method object response
Error responses
404objectThe customer does not exist or belongs to another shop.
422objectValidation failed, for example a missing token or a gateway_id that does not belong to this shop.
Remove a stored payment method and detach it at the gateway. When it was the customer's default payment method, the default is cleared as well. The payment method must belong to the customer in the path.
Path parameters
customer_idRequiredintegerCustomer ID
Format: integer.
payment_method_idRequiredintegerPayment method ID
Format: integer.
ReturnsPaymentMethod
The deleted payment method
Error responses
404objectThe customer or the payment method does not exist, the customer belongs to another shop, or the payment method belongs to another customer.