---
title: "Your own front end"
description: "Run your store's website or app on your own code, with the customer API behind it."
---

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

# Your own front end

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`](/customer-api/errors#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](/customer-mcp) keep working on every plan. See [Plans](/overview/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](/customer-api/authentication#register-an-app) 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](/customer-api/authentication#your-own-sign-in).

Each client has a **Rate limit** and an optional **Quota**; see [Limits](/customer-api/limits).

> **Verified apps**
>
> An app that registered itself is **Not verified** until you choose **Verify app** for it. Until then it can't pay with customers' saved cards, remove them, set refund waivers or resume or change subscriptions, and its consent page tells customers it's unverified. A client with a secret you created is yours, so it has none of these limits. Verify only an app you trust.

## 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}`](/customer-api/reference/get-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](/customer-api/errors).

```ts title="sherpo.ts"
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;
  }
};
```

```ts
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](/customer-api/authentication#refresh-and-revoke) shows, and retry a call that answered `401` once with the new one.

## What's next

- [Authentication](/customer-api/authentication): signing customers in.
- [Building a storefront](/customer-api/storefront): the catalog, product pages and pages.
- [Checkout](/customer-api/checkout) and [A customer's library](/customer-api/library).

Source: https://docs.sherpo.io/customer-api/self-hosted/index.mdx
