Create a customer
Creates a customer. Every field is optional, so you can send an empty body and fill the customer in later. Give the customer a username and password so they can sign in later (see Log in a customer).
Secret and limited tokens. A customer created with a limited token is tied to that token, so it can read and update the customer. A limited token cannot set tax_exempt.
You cannot add cards here: save them with Add a payment method, or with a payment that has save: true. Sending cards is a 400. No email is sent and no event fires.
AuthorizationBearer <token>A secret, trusted or limited token. See Authentication.
expand?stringComma-separated child objects to return in full instead of as a URL, for example customer,payments. Use dot notation for nested objects (items.product), up to four levels deep. A single object takes up to 12 paths; a list takes up to 2, applied to every item. Extra paths are dropped without an error. See Expanding objects.
show?stringComma-separated fields to return; all others are left out. Use dot notation for child fields (customer.email). You cannot send show and hide together (400). See Customizing output.
hide?stringComma-separated fields to leave out of the response. Use dot notation for child fields (customer.email). You cannot send show and hide together (400). See Customizing output.
formatted?booleanWhen true, the object also has a formatted child with amounts and dates as display text in the shopper's language and currency (for example $19.99 or November 7, 2026). The default is false. See Localized formatting.
falseapplication/json- body
The fields you send to create or update a customer. Every field is optional. On an update, only the fields you send change. The same object is used for the customer of a cart, invoice or payment.
customer_id?stringOn create only: your own id for the customer. Letters, numbers, underscores, dashes and periods, and it must not be in use. Leave it out and Comecero makes one. On an update it must match the id in the URL. On a cart, invoice or payment, sending the id of an existing customer updates that customer.
length <= 30company_name?|The customer's company name.
length <= 75name?|The customer's name.
length <= 75email?stringThe customer's email address. Must be valid. Once set it can be changed but not cleared: null on an update is ignored.
emaillength <= 75phone?|The customer's phone number.
length <= 25billing_address?|The billing address. On an update, null clears it.
shipping_address?|The shipping address. On an update, null clears it.
username?stringA username so the customer can sign in (see Log in a customer). Stored in lower case. Must not be taken by another customer of the account (409). It can be changed later.
5 <= length <= 25password?stringThe customer's password, used with the username. Stored hashed, never returned.
6 <= length <= 50tax_number?|The customer's tax or VAT number. For a customer in an EU country, the number is checked with the EU VIES service: an invalid number is a 400, and 422 means the service could not be reached (try again). A valid EU number makes the customer tax exempt. A GB number does not.
tax_exempt?booleanSet the customer tax exempt. Only a secret token can set this; from a limited token it is ignored. It has no effect for a customer in an EU country (not GB), where tax_number decides. On a reseller account only Comecero staff can change it.
locale?|The customer's language and region, for example en-US. Read on update only. On create, the locale of the request is used.
meta?unknownYour own data for this customer, as an object or a string. At most 2,048 characters when serialized.
The new customer.
application/json- response
A customer: the person or company who buys. Holds contact details, the billing and shipping address, an optional username for sign-in, and links to the customer's payment methods, store credit and history.
The links (payment_methods, payments, refunds, orders, subscriptions, invoices, balance) are only present when your token may read that resource. Send expand to get any of them in full. In a list of customers, orders is left out and payments, refunds, subscriptions and invoices are never expanded.
object*"customer"The object type. Always customer.
"customer"url*stringThe full URL of the customer.
customer_id*stringThe id of the customer.
date_created*stringWhen the customer was created.
date-timedate_modified*stringWhen the customer was last changed.
date-timeaccount_id*stringThe id of the account the customer belongs to.
test*booleanTrue for a test customer, false for a live one.
company_name*|The customer's company name.
name*|The customer's name.
email*|The customer's email address.
emailphone*|The customer's phone number.
billing_address*A postal address, as it comes back on a customer (billing_address, shipping_address), on a saved card or wallet, and on the customer of a cart, invoice or order. An address that was never set still comes back as an object, with every field null.
shipping_address*A postal address, as it comes back on a customer (billing_address, shipping_address), on a saved card or wallet, and on the customer of a cart, invoice or order. An address that was never set still comes back as an object, with every field null.
username*|The username the customer signs in with (see Log in a customer). Always lower case. The password is never returned.
tax_number*|The customer's tax or VAT number.
tax_exempt*booleanTrue when no tax is charged to the customer. For a customer in an EU country (not GB), this is true exactly when a valid VAT number is on file.
has_payments*booleanTrue once the customer has made at least one successful payment.
locale*|The customer's language and region, for example en-US. Used for the emails the customer gets.
meta*unknownYour own data for this customer, as an object or a string.
payment_methods?|The URL of the customer's saved payment methods, or the list itself when expanded.
payments?|The URL of the customer's payments, or the list when expanded.
refunds?|The URL of the customer's refunds, or the list when expanded.
orders?|The URL of the customer's orders, or the list when expanded. Not present in a list of customers.
subscriptions?|The URL of the customer's subscriptions, or the list when expanded.
invoices?|The URL of the customer's invoices, or the list when expanded.
balance?|The URL of the customer's store credit balance, or the balance itself when expanded.
formatted?Only when you send formatted=true. Dates as display text.
curl -X POST 'https://api.comecero.com/api/v1/customers' \ -H 'Content-Type: application/json' \ -d '{ "name": "John Doe", "email": "john@example.com"}'{ "object": "customer", "url": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3", "customer_id": "0091304300408CuoxY9Pf3", "date_created": "2026-11-02T18:18:20Z", "date_modified": "2026-11-02T18:18:20Z", "account_id": "AB1234", "test": true, "company_name": null, "name": "John Doe", "email": "john@example.com", "phone": "555-555-0123", "billing_address": { "object": "address", "name": "John Doe", "address_1": "123 Main St.", "address_2": null, "city": "New York", "state_prov": "NY", "postal_code": "10019", "country": "US", "email": "john@example.com", "meta": null }, "shipping_address": { "object": "address", "name": null, "address_1": null, "address_2": null, "city": null, "state_prov": null, "postal_code": null, "country": null, "email": null, "meta": null }, "username": "johndoe", "tax_number": null, "tax_exempt": false, "has_payments": true, "locale": "en-US", "meta": null, "payment_methods": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/payment_methods", "payments": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/payments", "refunds": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/refunds", "orders": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/orders", "subscriptions": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/subscriptions", "invoices": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/invoices", "balance": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3/balance"}List customers GET
Lists the customers of your account, oldest first. Search with `q` and filter by date or by whether the customer has paid. The list is cursor-based: follow `next_page_url`, or send `after_item` or `before_item`. It does not take `sort_by`; use `date_type` with `desc`. Secret tokens only. A limited token cannot list customers.
Log in a customer POST
Signs a customer in with the `username` and `password` set on the customer. Three ways to call it: - With a limited token: on success that token is tied to the customer. It can then read and change the customer, their payment methods, orders, subscriptions and invoices, and use `me` as the customer id. No new token is returned. - With no token: send `account_id` (and `test=true` for a test customer) in the query. A new limited token for the customer comes back in `auth`. - With a secret token: you must send the shopper's `user_ip_address` in the query, and the token needs permission to create auths and update customers. A new limited token for the customer comes back in `auth`. Every attempt waits about half a second. After too many failed attempts the customer is locked out for 10 minutes (`401`).