Entitlements, Credits & Limits

What a customer has is one answer, CustomerInfo, whatever store they bought in: their entitlements (pro), their credits (tokens) and their use of each limit (ai_requests a month). The apps read it to decide what to show; your server reads it to decide what to serve — and spends credits and quota, which only a server does.

Quick example

A route only Pro customers reach, and one that is paid for in tokens:

// src/modules/summaries/summaries.controller.ts
import { Body, Controller, Forbidden, Get, Headers, PalError, Palbase, Post, User, z, type UserT } from "palbase/backend";
import { PalbaseError, isEntitled, withReservation } from "palbase/server";

const Summarize = z.object({ text: z.string().min(1).max(20000) });
type Summarize = z.infer<typeof Summarize>;
const Retried = z.object({ "idempotency-key": z.string().min(1).max(255) });
type Retried = z.infer<typeof Retried>;

@Controller("/summaries")
export class SummariesController {
  @Get("/archive")
  async archive(@User() user: UserT): Promise<{ pro: true }> {
    const { data } = await Palbase.purchases.getCustomer({ path: { customer_id: user.id } });
    if (!isEntitled(data, "pro")) throw new Forbidden("Pro is needed", "entitlement_required");
    return { pro: true };
  }

  @Post("")
  async create(@Body(Summarize) body: Summarize, @Headers(Retried) headers: Retried, @User() user: UserT): Promise<{ summary: string }> {
    try {
      // 10 tokens are held while the job runs and taken once it returns; if it throws, they are released.
      // The same Idempotency-Key again (a retried request) is the same hold, never a second charge.
      return await withReservation(Palbase, user.id, { credits: "tokens", amount: 10, idempotencyKey: headers["idempotency-key"] }, async () => {
        const summary = await Palbase.ai.ask(`Summarize in three sentences:\n\n${body.text}`);
        return { summary };
      });
    } catch (e) {
      if (e instanceof PalbaseError && e.code === "credits_insufficient") throw new PalError(402, "credits_insufficient", "Not enough tokens");
      throw e;
    }
  }
}

A customer without 10 tokens available is refused before the job runs: the purchases module answers 409 credits_insufficient, and the route answers 402. A module's refusal the handler does not catch answers 500 (Responses & Errors).

What a customer has

CustomerInfo is what GET /purchases/me answers the customer's app and GET /purchases/customers/{customer_id} answers your server — the same document:

An entitlement:

An entitlement is read from the source that gives it longest: one for life wins, a real purchase wins over a test one.

A subscription's state is trial, active or grace while it gives access, and pending, billing_retry, paused, expired, revoked (refunded) or replaced (another purchase took it over) when it does not.

Checking an entitlement

On your server, read the customer and ask isEntitled(info, key) from palbase/server: the entitlement is active and, unless it is for life, ends after now. It reads the CustomerInfo alone, so one kept a while still ends when its entitlement does. In a palbase/backend app the module is Palbase.purchases; from any server, createServer({ url, secretKey }).purchases. Reading a customer writes nothing: a user who has bought nothing reads as a customer with nothing — and with every limit's free tier.

In the app, what the customer has is kept current on its own:

The app's answer decides what the app shows. What a purchase opens on your server — content, an API, a download — is checked on the server: the app's word is the app's.

Credits

A customer's credits come from the catalog's products — a consumable per purchase, a subscription per period — and from grants your support gives. Each lot keeps its own end: a subscription period's credits end with the period unless the product rolls them over (rollover: "all"), credits bought never end, and a grant's may.

Spending

Credits are spent by your server, with the secret key, in one of two ways.

In one step, for work that is done or cannot fail:

// src/modules/exports/exports.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class ExportsService {
  /** Takes 5 tokens for the export: the same exportId again is the same spend, never a second. */
  async charge(userId: string, exportId: string): Promise<number> {
    const { data } = await Palbase.purchases.spend({
      path: { customer_id: userId },
      headers: { "Idempotency-Key": `export-${exportId}` },
      body: { credits: "tokens", amount: 5, metadata: { export: exportId } },
    });
    return data.balance_after ?? 0;
  }
}

Held for a job, then committed. A hold keeps the credits — still the customer's, but no other spend can take them — until it is committed (the job ran: commitSpend, all of it or amount of it), released (it did not: releaseSpend) or runs out (ttl_seconds, 10 minutes unless said, 24 hours at most; extendHold gives it more). withReservation(server, customerId, reservation, fn) from palbase/server does the three: it holds, runs fn, commits when fn returns and releases when it throws. Asked again with an idempotencyKey whose hold is already over, it throws ReservationSettled, and the job does not run again.

reverseSpend hands back what a committed spend took — the job failed afterwards — to the lots it came from.

Credits are taken from the lots that expire first, bought ones last. The Idempotency-Key names a spend for good: sent again, a minute or a month later, it answers the same spend (200, Idempotent-Replayed), never a second. Every movement — given, spent, expired, taken back by a refund, forgiven — is listed by listCreditEntries, newest first: support's answer to "where did my credits go".

Giving credits

// src/modules/support/support.service.ts
import { Injectable, Palbase } from "palbase/backend";

@Injectable()
export class SupportService {
  async apologize(userId: string, ticket: string): Promise<void> {
    await Palbase.purchases.grantCredits({
      path: { customer_id: userId },
      headers: { "Idempotency-Key": `ticket-${ticket}` },
      body: { credits: "tokens", amount: 50, source: "support", reason: `Ticket ${ticket}: export failed twice`, expires_at: "2027-01-01T00:00:00Z" },
    });
  }
}

A grant pays what the customer owes first. source is promotion or support, and reason is the record. forgiveCredits takes a debt off — all of it, or amount of it — when support lets a refunded spend go. Studio's Purchases › Customers gives credits too.

A balance that falls under its credit's low_at emits purchases.credits.low, once until it is back above; one that comes to nothing, purchases.credits.depleted.

Limits

A limit is a quota counted in a window — calendar_month, calendar_day (from midnight in the project's time zone) or billing_period — with a free tier for everyone, and what each product gives on top: a customer gets the largest of their products'.

A limit is spent as credits are — spend, holdSpend, withReservation — naming limit instead of credits:

// src/modules/ai/quota.ts
import { Palbase } from "palbase/backend";

export async function countRequest(userId: string, requestId: string): Promise<void> {
  await Palbase.purchases.spend({
    path: { customer_id: userId },
    headers: { "Idempotency-Key": requestId },
    body: { limit: "ai_requests", amount: 1 },
  });
}

Past the window's max, a limit with overflow takes credits instead (per_unit of them a unit), and one without is refused: 409 limit_reached. A hold counts in the window it was made in, even when it is committed after the window ends.

The refusal says what would give the customer more, for the app to offer: upgrades lists the entitlements whose products give more of the limit than the customer has now, the smallest step up first — empty when no product gives more.

{
  "error": "limit_reached",
  "error_description": "the customer used this window's limit",
  "status": 409,
  "request_id": "req_…",
  "limit": "ai_requests",
  "upgrades": [{ "entitlement": "pro", "name": "Pro", "product": "pro", "max": 500 }]
}

setCustomerLimit gives one customer their own max — more for a customer support looks after, less for one who abuses it — until expires_at or clearCustomerLimit; grantLimit gives more units in the window it is in now. Each says why (reason).

A window used to 80% emits purchases.quota.threshold, and used to the end purchases.quota.exhausted, each once a window.

Events

Each change of what a customer has emits an event to the project's webhooks and to a palbase/backend app's @On handlers (Event Hooks, Webhooks):

// src/modules/premium/purchase-events.ts
import { Log, On, type PlatformEvent } from "palbase/backend";

export class PurchaseEvents {
  @On("purchases.subscription.changed")
  changed(event: PlatformEvent<"purchases.subscription.changed">): void {
    const { customer_id, product, change, store, expires_at } = event.data;
    if (change === "billing_issue") Log.warn("renewal not charged", { customer_id, product, store, expires_at });
  }
}

The customer's own apps hear of their changes on their realtime channel and read what they have again; the SDKs do it for you.

Related

• Customers: one customer's page, grants, guests and settings
• Catalog: the entitlements, credits and limits a product gives
• Server SDK: createServer, refusals as PalbaseError, retries
• Event Hooks: @On in a palbase/backend app