comecerodocs
Customers

Log in a customer

POST
/customers/login

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).

Authorization

bearer
headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Query Parameters

account_id?string

The account the customer belongs to. Required when you send no token. Not allowed with a token.

test?boolean

true to sign in a test customer. Only when you send no token; with a token, its mode is used and sending test is a 400.

Defaultfalse
user_ip_address?string

The shopper's IP address, when your server calls with a secret token on the shopper's behalf. Comecero uses it for fraud checks and to find the shopper's country. Only read for a secret token: for every other token the address the request comes from is used. A value that is not a valid IPv4 or IPv6 address is ignored.

expand?string

Comma-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?string

Comma-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?string

Comma-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?boolean

When 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.

Defaultfalse

Request Body

application/json
  1. body

The customer's sign-in details.

username*string

The customer's username. Not case sensitive.

password*string

The customer's password.

Response Body

The customer. With no token or a secret token, auth holds the new limited token.

application/json
  1. response

The customer who signed in. When the request was made without a token or with a secret token, auth holds a new limited token for that customer. When the request was made with a limited token, auth is left out: that token now acts for the customer.

object*"customer"

The object type. Always customer.

Value in"customer"
url*string

The full URL of the customer.

customer_id*string

The id of the customer.

date_created*string

When the customer was created.

Formatdate-time
date_modified*string

When the customer was last changed.

Formatdate-time
account_id*string

The id of the account the customer belongs to.

test*boolean

True 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.

Formatemail
phone*|

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*boolean

True 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*boolean

True 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*unknown

Your 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.

auth?

The new limited token for the customer. Only here when the request had no limited token. Keep token: it is shown only this once.

Example Request
curl -X POST 'https://api.comecero.com/api/v1/customers/login' \  -H 'Content-Type: application/json' \  -d '{  "username": "johndoe",  "password": "s3cret-pass"}'
Example Response
{  "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": null,  "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",  "auth": {    "object": "auth",    "url": "https://api.comecero.com/api/v1/auths/5d1f0c3e9b7a4f2e8c6d1a0b3e5f7a9c",    "auth_id": "5d1f0c3e9b7a4f2e8c6d1a0b3e5f7a9c",    "test": true,    "account_id": "AB1234",    "account_alias": "example-shop",    "type": "limited",    "ip_address": "203.0.113.10",    "token": "lt_test_example_token",    "expires": "2026-11-03T18:20:00Z",    "expires_in_seconds": 86400,    "date_last_used": null,    "comments": null,    "date_created": "2026-11-02T18:20:00Z",    "date_modified": "2026-11-02T18:20:00Z",    "customer": "https://api.comecero.com/api/v1/customers/0091304300408CuoxY9Pf3",    "roles": null,    "permissions": null,    "effective_permissions": []  }}

Create a customer POST

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.

Email a sign-in link POST

Emails a customer a link that signs them in to your app without a password, for example to see past orders and downloads. The customer is found by email address. When several customers of the account have that email, the newest gets the link and the email offers the others too (up to 10). The link opens `https://<your app host>/link` and works for 4 hours. The account needs an app host in its technical settings and a notification set up for customer links, or the call fails with `422`. No token is needed. Every input is in the query string; there is no body.