First customer - Unprice Documentation

Create or map one customer before you enforce a paid action. The customer is the economic actor in Unprice: subscriptions, entitlements, budgets, wallets, usage, and invoices are tied to this ID. Use customers.signUp when Unprice should provision the customer money path from a plan version:

customer record
subscription and active phase
entitlements from the published plan version
billing periods
wallet and initial credit policy when configured
checkout redirect when the plan needs payment-provider setup

Install the SDK

npm install @unprice/api

pnpm add @unprice/api

import { Unprice } from "@unprice/api";

const unprice = new Unprice({
  token: process.env.UNPRICE_TOKEN
});

const { result, error } = await unprice.customers.signUp({
  name: "Acme Inc.",
  email: "buyer@example.com",
  planSlug: "pro",
  externalId: "acct_123",
  successUrl: "https://yourapp.com/billing/success",
  cancelUrl: "https://yourapp.com/billing/cancel"
});

if (error) {
  throw new Error(error.message);
}

if (!result.success) {
  throw new Error(`Customer signup is incomplete. Continue at ${result.url}`);
}

await db.accounts.update({
  where: { id: "acct_123" },
  data: {
    unpriceCustomerId: result.customerId
  }
});

Use planSlug to sign up for the latest published version of a plan, or planVersionId to pin the customer to a specific published version.

Your app calls Unprice signUp, Unprice validates data, redirects to a payment provider when needed, then returns the Unprice customer ID. — Customer signup flow

Follow the returned url to complete payment setup when required. A returned customer ID alone does not mean the subscription is ready for paid work. Confirm access before the first action. Use the returned customerId in runtime calls:

const { result, error } = await unprice.access.check({
  customerId: account.unpriceCustomerId,
  featureSlug: "ai-generations"
});

Next steps

One paid action

Put the first paid action on the money path.

Customer signup SDK

See the full customers.signUp request and response shape.