Connect your systems

ORBCART DOCUMENTATION

Signed-in buyers

Use your shop's existing login. OrbCart keeps no accounts; it trusts your ID tokens.

Buyers sign in with your identity system: Better Auth, Auth0, Clerk, Keycloak, your own. OrbCart checks the ID token and keeps only its issuer and subject. No passwords, no profiles, no second user database.

What signing in gives the buyer:

  • One Cart on every device. Lines from a guest Cart join their own Cart.
  • Their own prices. Your offers function sees context.buyer.
  • Their Orders, including earlier guest Orders to the same verified email.

1. Trust your identity system

src/worker.ts
export default defineCommerce({
  channels,
  offers,
  identity: {
    issuers: [{ issuer: "https://auth.example.com", audience: "shop" }],
  },
});

OrbCart finds the keys through OpenID discovery. If your issuer has no discovery document, name the key set yourself:

{ issuer: "https://shop.example.com", audience: "shop", jwks: "https://shop.example.com/api/auth/jwks" }

2. Send the token from the storefront

Give createCommerce a function that returns the current ID token, or undefined while nobody is signed in. It is asked before every request:

const commerce = createCommerce({
  url,
  key,
  buyer: () => auth.getIdToken(),
});

When OrbCart rejects a token, it asks once more with that token as refused and retries the request with the fresh one. If your identity system caches tokens, renew there:

const commerce = createCommerce({
  url,
  key,
  buyer: (asked) => auth.getIdToken({ forceRefresh: asked?.refused !== undefined }),
});

3. Claim the Cart after sign-in

Right after the buyer signs in, call identify(). Continue with the Cart it returns:

const { access, merged } = await cart.identify();

saveCartToken(access.token);
if (merged) showToast("We added the items from your other device.");

access is usually the same Cart. It is a different one when the buyer already had a Cart elsewhere that took over these Lines.

Show the buyer's Orders

const page = await commerce.orders();
const older = page.next ? await commerce.orders({ after: page.next }) : undefined;

Newest first, in this Channel only.

Prices per customer group

export const offers: OffersContract = async (lines, { buyer, currency }) => {
  const group = buyer ? await crm.groupOf(buyer.subject) : "retail";
  return pricing.offers(lines, { group, currency });
};

buyer is { issuer, subject }. It is never a profile, so your CRM stays the source of names and groups.

Sign-in inside the React checkout

@orbcart/client/better-auth connects Better Auth to both the checkout and the client. A known email address is offered a sign-in right in the checkout:

import { betterAuthIdentity } from "@orbcart/client/better-auth";

const identity = betterAuthIdentity({
  client: authClient,
  knows: (email) =>
    fetch("/api/has-account", { method: "POST", body: email }).then((r) => r.json()),
});

const commerce = createCommerce({ url, key, buyer: identity.buyer });

<Checkout
  cart={cart}
  locale="en-GB"
  identity={identity}
  onSignedIn={(access) => setCart(access)}
/>;

Your Better Auth server needs the emailOTP and jwt plugins. Rate-limit the knows endpoint and protect it with a bot check, such as Turnstile.

Good to know

  • Signing out ends the Cart on that device. A buyer's Cart only opens next to their token. The next add() starts a fresh guest Cart.
  • Someone else's Cart on a shared computer? identify() notices and gives the buyer their own.
  • Discount limits per buyer count signed-in buyers by identity and guests by email. Discounts →

Build the Cart →

On this page