Skip to main content

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

Errors

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