Customers

Everyone who has bought from this store, with their order count, lifetime revenue and, on a store that keeps customer accounts in its own database, the state of each account. db_identity on the response says whether this store does; when it is false there is no account to manage and invite_customer, clear_customer_2fa and set_customer_state do not apply. Money is in minor units. Lifetime revenue is one currency's: the base currency unless you pass currency, named in currency on the response on a store with orders in more than one. A customer who also ordered in other currencies has other_currencies on their row, one entry each with orders, total_minor and average_order_minor, so a customer with only euro orders reads as euro orders and not as nothing spent.

One customer with their lifetime stats (in one currency, with other_currencies beside them for anything they ordered in other currencies), their orders including canceled and refunded ones, their saved address book, the state of their account, and any panels contributed by add-on plugins such as a subscription or a membership. The address book is where they are now; an order's address is where they were at checkout, and the two are kept apart on purpose.

Open a store account for this customer if there is none yet and queue the set-password email, the same message and the same token machinery the checkout opt-in uses. Sending a second one invalidates the first, which is what anybody clicking resend means by it. Answers 409 on a store that does not keep customer accounts in its own database, and 409 when a Grav user account already holds the address, because that account signs in instead.

Queue a single-use, short-lived link that signs this customer in, to the address on their record and never to one supplied here. For the buyer who orders twice a year and does not remember a password. The link is minted when the mail leaves rather than when this is called, so a queue running behind never posts a link that has already lapsed, and issuing one invalidates any outstanding link for that customer. Setting a password invalidates every outstanding link too. Answers 409 when sign-in links are switched off, and 422 for an account with no password yet — that customer wants the set-password invitation, which is the step that proves the address.

Destroy the authenticator secret on a customer's account, for the case where somebody lost their phone. Nothing is shown and nothing is handed back: this removes a lock rather than reading a key, and the customer enrolls a new device after signing in with their password. Answers 404 when the customer has no account.

Switch a customer's ability to sign in on or off. Disabled is refused at authorization and invalidates an existing session on its next request. Nothing commercial moves: the customer record, the orders, the invoices and the download grants all stay exactly as they were. Answers 404 when the customer has no account.

A customer's address book, default billing and shipping addresses first. Each row carries the address fields under address, its label, and is_default_billing / is_default_shipping. The same rows get_customer carries, without the rest of the record. This is where they are now; an order's address is where they were at checkout.

Save an address for a customer, for example one taken over the phone. Checked exactly as the customer's own account page checks one: at least a street, town, postcode or country, a country that is an ISO 3166-1 code, and a state the country has for the countries that list them (stored as its code). A failure is a 422 saying what is wrong. Set is_default_billing or is_default_shipping to make it the default of that kind, which demotes whichever address held it. Answers with the new row and the whole book.

Change one address in a customer's book. Only the keys sent change; a field, the label or a default flag left out keeps what it had, and an empty string clears a field. The whole address is checked again the way create_customer_address checks it. false on a default flag stops this address being that default without promoting another. Answers 404 when the address is not in this customer's book.

Remove an address from a customer's book. When it was a default, no other address is promoted in its place. Orders already sent there keep their own copy. Answers 404 when the address is not in this customer's book.

Make one saved address the customer's default billing or shipping address, the one checkout and the admin's New order form start on. Whichever address held that default stops holding it.