React

Our React hooks make it a lot easier to evaluate feature access and usage on the frontend. Since PriceOS can only be safely used on the backend, using these hooks still requires server-side setup, but we’ve created helpers to make this really easy for you.

Make sure your API key is only used server side. It should never be used client side.

Be sure to read Linking Stripe Customers to learn how to link Stripe customers to your own interal ID.

Install

Create an API key in the PriceOS dashboard and add to your environment variables.

.env

PRICEOS_API_KEY=pos_ab234cdef...

npm i priceos

Add server side handlers

Next.js
Other backends

// app/api/priceos/[...path]/route.ts
import { priceosHandler } from "priceos/next";

export const { GET, POST } = priceosHandler({
  identifyCustomer: async (req: Request) => {
    // Return a customer identity from your server
  },
});

If you need to include an auth token from the client, you can do so on the Provider.

We are working on adding more helpers for other backends. If there’s a backend you would like us to create helpers for, please reach out and let us know.

Depending on which react hooks you want to use, you’ll need to implement the following routes…

Hook	Endpoint(s) you must add
`useCustomer`*	`GET /priceos/v1/customer`
`useFeatureAccess`	`GET /priceos/v1/feature-access`
`useTrackUsage`	`POST /priceos/v1/usage`
`useUsageEvents`	`GET /priceos/v1/usage-events`
`useCheckout`	`POST /priceos/v1/checkout`
`useCustomerPortal`	`POST /priceos/v1/customer-portal`

* If you use trackUsage from useCustomer, add POST /priceos/v1/usage. If you use checkout from useCustomer, add POST /priceos/v1/checkout.

Make sure you resolve customerId from your server-side auth/session.

If you need to include an auth token from the client, you can do so on the Provider.

useCustomer()

Requires a GET /priceos/v1/customer endpoint.

app.get("/priceos/v1/customer", async (req, res) => {
  const customerId = await identifyCustomerFromSession(req);
  const data = await priceos.customers.get(customerId);
  res.json(data);
});

useFeatureAccess()

Requires a GET /priceos/v1/feature-access endpoint.

app.get("/priceos/v1/feature-access", async (req, res) => {
  const customerId = await identifyCustomerFromSession(req);
  const data = await priceos.features.getAccess(customerId);
  res.json(data);
});

useTrackUsage()

Requires a POST /priceos/v1/usage endpoint.

app.post("/priceos/v1/usage", async (req, res) => {
  const featureKey = req.body?.featureKey;
  const amount = req.body?.amount ?? 1;
  if (amount <= 0) // Return an error
  const customerId = await identifyCustomerFromSession(req);
  const data = await priceos.usage.track({
    customerId,
    featureKey,
    amount,
    eventKey: req.body.eventKey,
    occurredAt: req.body.occurredAt,
    metadata: req.body.metadata,
  });
  res.json(data);
});

Don’t allow negative numbers from client for security reasons.

useUsageEvents()

Requires a GET /priceos/v1/usage-events endpoint.

app.get("/priceos/v1/usage-events", async (req, res) => {
  const featureKey = req.query.featureKey
  const customerId = await identifyCustomerFromSession(req);
  const data = await priceos.usage.listEvents({
    customerId,
    featureKey,
    period: req.query.period,
    offset: req.query.offset,
    limit: req.query.limit,
    customRange:
      req.query.start && req.query.end
        ? { start: req.query.start, end: req.query.end }
        : undefined,
  });
  res.json(data);
});

useCheckout()

Requires a POST /priceos/v1/checkout endpoint.

app.post("/priceos/v1/checkout", async (req, res) => {
  const body = req.body ?? {};
  const customerId = await identifyCustomerFromSession(req);

  const data = await priceos.customers.createCheckout(customerId, {
    productKey: body.productKey,
    stripePriceId: body.stripePriceId,
    successUrl: body.successUrl,
    cancelUrl: body.cancelUrl,
    metadata: body.metadata,
    customerInfo: body.customerInfo,
    checkoutParams: body.checkoutParams,
  });
  res.json(data);
});

useCustomerPortal()

Requires a POST /priceos/v1/customer-portal endpoint.

app.post("/priceos/v1/customer-portal", async (req, res) => {
  const customerId = await identifyCustomerFromSession(req);
  const data = await priceos.customers.createPortal(customerId);
  res.json(data);
});

Add provider component

// layout.tsx or wherever your providers are
import { PriceOSProvider } from "priceos/react";

<PriceOSProvider>
  {/* children */}
</PriceOSProvider>;

For full Provider configuration details, see PriceOSProvider.

Generate types (optional, but highly recommended)

npx priceos generate-types

This will generate a local types file that you can include so all of your features are fully typed.Run with --help to see more configuration options.

Remember to regenerate types any time you create a new feature.

Read feature access

import { useFeatureAccess } from "priceos/react";
import type { MyFeatures } from "./priceos.types";

export function PrioritySupportButton() {
  const { hasAccess } = useFeatureAccess<MyFeatures>("priority_support");

  const onClick = () => {
    if (hasAccess){
      // Allow access
    }
  }

  return <button onClick={onClick}>Contact support</button>;
}

Track usage (optional)

Only if you’re using PriceOS to track your customers’ usage for limit features.

import { useTrackUsage } from "priceos/react";
import type { MyFeatures } from "./priceos.types";

export function SeatButton() {
  const { trackUsage } = useTrackUsage<MyFeatures>();

  async function handleClick() {
    // Add teammate first
    await trackUsage({
      featureKey: "team_seats",
      amount: 1,
      eventKey: `add_team_seat_${Date.now()}`,
    });
  }

  return <button onClick={handleClick}>Add teammate</button>;
}

If the action happens on your backend (for example in a server action, webhook, or background job), it usually makes more sense to track usage on the backend instead.

useTrackUsage with the built-in Next.js handlers (priceos/next) only accepts positive amount values (so that clients can’t reverse their usage). For negative adjustments (for example when removing a team seat), track usage from your backend via the Node.js SDK or REST API endpoints.

For more info see Tracking usage.

Getting Started

Features

Products

Customers

Usage

Bonuses

Overrides

Account

useCustomer()

useFeatureAccess()

useTrackUsage()

useUsageEvents()

useCheckout()

useCustomerPortal()

Getting Started

Features

Products

Customers

Usage

Bonuses

Overrides

Account

​useCustomer()

​useFeatureAccess()

​useTrackUsage()

​useUsageEvents()

​useCheckout()

​useCustomerPortal()

useCustomer()

useFeatureAccess()

useTrackUsage()

useUsageEvents()

useCheckout()

useCustomerPortal()