Customer Portal

Archetype Portals

The Archetype Portals provides customer and pricing portals

About Archetype

Archetype is the revenue infrastructure that make API monetization quick and painless. It works by integrating powerful, reliable purchase server with cross-platform support. Our open-source framework provides a backend and a wrapper around payment processors like Stripe to save engineers months from having to build custom billing infrastructure for their APIs.

Whether you are building a new API or already have millions of customers, you can use Archetype to:

Sign up to get started.


If looking to use our APIs directly, the API reference is here.

With Archetype, you can keep track of all your app transactions in one place — whether your customers are charged through iOS, Android, or the web. As the single source of truth for your API business, we make sure your customers' subscription status is always up to date.


Explore the docs and view the quickstart guide

Install the package from NPM, @archetypeapi/portals

npm i @archetypeapi/portals


react: "^18.1.0",


After installing the NPM package we can import the Customer Portal react component and then utilize it.

import { CustomerPortal } from "@archetypeapi/portals";
import "@archetypeapi/portals/dist/styles.css";
import "@archetypeapi/core/dist/styles.css";

export default function Home() {
  return (
      <CustomerPortal token={"token_from_sdk"} stripePubKey={"stripe publishable key from stripe dashboard"} defaultView={"dashboard"} />

We will also need to import css files, This would be the root file in your react application or next.js application. This is important.

import "@archetypeapi/portals/dist/styles.css";
import "@archetypeapi/core/dist/styles.css";

The archetype web token is important in authentication a user and this can be genereated using the Archetype Python SDK or Archetype Node SDK on you backend servers. Please do no reveal the archetype app_id or api keys anywhere on the frontend.

The archetype web token expires every 60 minutes. After it expires the dashboard will display a session expired error.
This token needs to be reset and this can be done by creating a new token using the sdk.

Error Handling

The customer portals react component also has an error handling feature. You are able to send a useState handler as prop thought the react component and the linked state variable would get updated with the current error on customer portals. We can use this to handle error and can also be used to detect a session expired error and then regenerate the token.

const [err, errHandler] = useState<string>("");

useEffect(() => {
    // handle error here 
  }, [err]);


Custom configs

We can customize the UI and the logo on the sidebar by passing in a config object with the customer portal


const config = {
  primary: "#1c1c1c",
  secondary: "#525252",
  tertiary: "#383838",
  accent: "#05a36a",
  textDarkPrimary: false,
  textDarkSecondary: false,
  textDarkTertiary: false,
  logo: <Archetypelogo className="h-20 " />,
  returnHref: "/",

return <CustomerPortal token={token} defaultView={"billing"} config={config} />;
Customer portal configurations
  • Primary : Main color, affects sidebar and buttons
  • Secondary : Background color of the seperate tabs
  • Tertiary : Background color of different cards in tabs
  • textDarkPrimary : choose between black and white text color for the text on bg color primary
  • textDarkSecondary : choose between black and white text color for the text on bg color secondary
  • textDarkTertiary : choose between black and white text color for the text on bg color tertiary
  • logo : this can be any react component, Ideally you can make an SVG of your company logo as a react component and then pass it through the config as shown above.
  • returnHref : This is the return redirect href.

We can also choose what the initial view screen should be between the dashboard, invoices and the billing page. Default is dashboard.

defaultView = { defaultView }; //can choose b/w  "dashboard" || "invoices" || "billing"

Setting up backend server

The library needs to be configured with your account's app_id and secret key which is available in your Archetype Dashboard. Set archetype.app_id and archetype.secret_key to their values.

Please install express and node on your computer before testing the code below.


  "dependencies": {
    "@archetypeapi/node": "^1.1.0",
    "express": "^4.18.2"

To install the npm package, run:

yarn add @archetypeapi/node


npm install @archetypeapi/node

Finally use the below code as a starting code to get the token generation working.


const express = require("express");
const { ArchetypeApi } = require("@archetypeapi/node");

const app = express();
port = 5002;

// For the application to work as expected, these env variables need to be available.
// The app id and secret key can be found in the archetype dashboard

const appId = {ARCHETYPE_APP_ID}; //replace with your app id
const appSecret = {ARCHETYPE_SECRET_KEY}; //replace with your secret key
const Archetype = ArchetypeApi(appId, appSecret);

app.get("/", function (req, res, next) {
  res.send("hello world!");

app.get("/token/:custom_uid", async (req, res) => {
  //Obtain custom uid from request
  const custom_uid = req.params.custom_uid;
  try {
    //Call archetype sdk token endpoint
    const data = await Archetype.Token.getCustomerPortalsToken(custom_uid);
    if (data.token) {
        message: "Success",
        data: data,
    } else {
        message: "Failed",
        data: data,
  } catch (error) {
      message: "Failed",
      data: error,

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`);

Once you have gotten the token from the serve, you will have to pass it to the FE and then place it in the customer portal component as mentioned in the above sections