Skip to content

Your own front end

Run your store's website or app on your own code, with the customer API behind it.

Updated

Sherpo hosts a website for every store. You can also build your own, in any framework or as a mobile app, and use the customer API for everything the store holds: products and prices, pages, customers’ sign-in, checkout and each customer’s library. This is Sherpo in your own codebase.

Plans

Your own front end needs the Pro plan or Sherpo One. On Lite, or with no plan, every call to the customer API answers 403 not_permitted with the reason plan, and the store’s authorization server shows an error page before anyone signs in. The store’s own site and its customer MCP server keep working on every plan. See Plans for what each one includes.

Set it up in the merchant app

Everything a front end needs is under Settings, Connections, API clients. Create, for the same store:

  1. A publishable key

    Choose New client, then Publishable key as its kind. It lets your site’s front end read products and prices before anyone signs in. It’s public, so you paste it into your page’s source; it can only read. Under Allowed origins, add your site’s address (https://www.example.com), one per line: without one, only the store’s own site can use the key.

  2. A client for signing customers in

    For a site whose browser code signs customers in, the app can register itself with the store’s authorization server, and you verify it on the same page. For a site with a backend, choose New client, then Client with a secret: add its Redirect URIs (where customers come back after signing in) and its Allowed origins, pick what Customers let it do, and keep its secret on your server.

  3. Optionally, your own sign-in

    If your site already signs its customers in, turn on Signs in your own customers for a client with a secret. Your backend then gets a customer’s token with the client secret, without Sherpo’s sign-in: see Your own sign-in.

Each client has a Rate limit and an optional Quota; see Limits.

Which origins may call

A page on another origin can call the API from the browser. A preflight (OPTIONS) is answered for any origin, since the credential is a header, never a cookie. An answer is then readable from:

  • the store’s own origins: https://{store} for the hostname in the path, the store’s primary hostname, and the site set as Your website under Website, Settings;
  • the Allowed origins of the publishable key sent, or of the client that issued the customer’s token.

Origins added or removed take effect within 5 minutes. A refusal is readable from any origin, so your page can always tell why a call failed.

The store’s hostname

Every call names the store by one of its hostnames, /v1/stores/{store}. Use the one your customers know: its Sherpo subdomain, or a domain of its own. GET /v1/stores/{store} answers its primary hostname, and served_hostname, the first of its hostnames that is set up and reached (the primary first), with every such one in served_hostnames. Link customers to the store’s own pages on served_hostname when your app can’t do something itself.

A minimal client

The guides use this small client. It sends the publishable key until a customer signs in, then their token, and turns a failure into an error carrying the problem.

sherpo.tsts
export const API = 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io';
const PUBLISHABLE_KEY = '<publishable key>';

export class Problem extends Error {
  constructor(readonly status: number, readonly body: Record<string, unknown>) {
    super(String(body.detail || body.title || `HTTP ${status}`));
  }
}

/** Calls the customer API as a visitor, or as the customer whose token is given. */
export const sherpo = async <T>(
  path: string,
  { token, method = 'GET', body }: { token?: string; method?: string; body?: unknown } = {},
): Promise<T> => {
  const headers: Record<string, string> = token
    ? { Authorization: `Bearer ${token}` }
    : { 'Publishable-Key': PUBLISHABLE_KEY };
  if (body !== undefined) headers['Content-Type'] = 'application/json';
  const response = await fetch(`${API}${path}`, {
    method,
    headers,
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  if (!response.ok) throw await problemOf(response);
  const answer = parsed(await response.text());
  if (answer === NOT_JSON) throw new Problem(response.status, { detail: 'The answer is not JSON.' });
  return answer as T;
};

/** The problem a failed answer carries, or its first words when it isn't one, such as a proxy's error page. */
export const problemOf = async (response: Response) => {
  const text = await response.text();
  const answer = parsed(text);
  return new Problem(
    response.status,
    typeof answer === 'object' && answer !== null
      ? (answer as Record<string, unknown>)
      : { detail: text.slice(0, 200) || response.statusText },
  );
};

const NOT_JSON = Symbol('not JSON');

/** The JSON a text holds, `null` included; `NOT_JSON` for anything else, such as a proxy's HTML error page. */
const parsed = (text: string): unknown => {
  try {
    return JSON.parse(text);
  } catch {
    return NOT_JSON;
  }
};
const store = await sherpo<{ name: string; served_hostname: string | null }>('');
const products = await sherpo<{ items: { title: string }[] }>('/products?limit=12');

A token expires after 1 hour: refresh it before it does, as Authentication shows, and retry a call that answered 401 once with the new one.

What’s next

Type to search…

↑↓ navigate↵ selectEsc close