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.listandaccount.disconnectreturn 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.emailyour 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.
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 toaccount.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 samebuyer.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.
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.
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.