> ## Documentation Index
> Fetch the complete documentation index at: https://docs.henrylabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connected Accounts

> Check out on your buyer's own account at stores that support it

## What it is

Some stores check out on the buyer's **own account** at the store, so the
order lands in their order history and earns their rewards. For those stores,
you connect the buyer's login once, and every purchase for that buyer at that
store signs in with it.

* **Henry Labs never returns the login.** The password is stored encrypted.
  No endpoint returns it, or the username: `account.connect`, `account.list`
  and `account.disconnect` return only the store, the buyer, the status and
  when the login was connected.
* **Purchases only place the order.** Henry Labs signs in and checks out. It
  may add the shipping address to the account's address book, and it moves
  anything already in the buyer's bag to Save for later. It never edits or
  removes their saved addresses or cards.
* **The login belongs to one buyer at one store, for your app.** It is filed
  under the buyer's email: the `buyer.email` your purchases carry. Send each
  buyer's own email: if your purchases share one email across buyers, they
  all sign in with whichever login was connected last.

A store that checks out on the buyer's own account shows
`accountRequired: true` in `merchants.list`, `merchants.search` and
`merchants.retrieve`. `account.connect` returns `409` at any other store.

## Connect a login

Collect the buyer's login on your server and pass it to `account.connect`.
Don't log it or store it yourself.

```ts theme={null}
const res = await henry.account.connect({
  merchantHost: "uniqlo.com",
  buyerEmail: "jane@example.com",
  username: "jane@example.com",
  password: buyerPassword,
});

res.data.status; // "connected"
res.data.replaced; // true when this replaced an earlier login
```

`merchantHost` also accepts a URL (`https://www.uniqlo.com/us/en/`), which is
reduced to its host.

Connecting again for the same buyer and store **replaces** the login. When a
buyer changes their password, connect again with the new one.

Henry Labs doesn't check the login when you connect it. A wrong password
shows up on the buyer's first purchase at the store, which fails at sign-in,
before checkout.

A buyer who signs in to the store with Google or Apple has no password to
give. They need to set one at the store first, usually through its "Forgot
password" link.

## Purchase

Purchase as usual, with the same `buyer.email` you connected the login under.

A purchase is refused with `409` and `data.code: "ACCOUNT_REQUIRED"`, before
anything is charged, when a store in the cart checks out on the buyer's own
account and the buyer has no working login there: none is connected, or the
store would not sign in with the one connected (`failed` in `account.list`).
`data.merchantHosts` lists every such store, so you can connect a login at
each before you purchase again. Sandbox apps are refused the same way, so you
can test it.

Good to know:

* The store emails the buyer about the order, since it's their account.
  Henry Labs reads the order's status without signing in, so a store that
  shows orders only to signed-in customers may send no shipping updates.
* Cart checkout details and product details don't sign in either. They show
  the store's guest prices, and a store that needs a login to check out may
  not return a quote.

If the store won't sign in to the account, the order fails with
`error.code: "ACCOUNT_LOGIN_FAILED"`. That happens when the password is wrong,
the account is locked, the store asks for a code or a check only the buyer can
complete (for example, because they turned on two-step sign-in there), or the
login was disconnected before the purchase ran. The login then shows
`status: "failed"` in `account.list`, and the buyer's purchases at that store
are refused with `409` until you connect it again, so a rejected password
isn't used twice and can't lock the account. Ask the buyer to sign in at the
store themselves, then connect the login again.

## List and disconnect

`account.list` returns the stores a buyer has a connected login at, newest
first.

```ts theme={null}
const { data } = await henry.account.list({ buyerEmail: "jane@example.com" });

data.accounts; // [{ merchantHost: "uniqlo.com", status: "connected", ... }]
```

A login the store would not sign in with shows `status: "failed"`. Purchases
for the buyer at that store are refused until you connect the login again, so
check this list to ask the buyer for their login before they buy.

`account.disconnect` removes a login at once and erases it: Henry Labs no
longer holds the username or the password. The buyer's later purchases at
that store are refused until a login is connected again. It works at any store
you connected a login at, including one that no longer checks out on
customers' own accounts.

```ts theme={null}
await henry.account.disconnect({
  merchantHost: "uniqlo.com",
  buyerEmail: "jane@example.com",
});
```

## Errors

| Status | `data.code` | When |
| - | - | - |
| `400` | | A field is missing or invalid |
| `404` | `MERCHANT_NOT_FOUND` | No store has this host |
| `404` | `ACCOUNT_NOT_FOUND` | `account.disconnect`: no login is connected for the buyer there |
| `409` | `ACCOUNTS_NOT_SUPPORTED` | `account.connect`: the store doesn't check out on customers' own accounts |

These endpoints need checkout purchase access on your account, and return
`403` without it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.