billing

The methods of pd.billing. Inputs and outputs are described in Conventions; every method can also fail as described in Errors.

Methods

pd.billing.listCreditPackages(init?)

The credit packs on sale

GET /api/credit-packages

Returns the active credit packs in display order. Needs a signed-in session or API key but no workspace permission. A pack without a Stripe price is still listed, with purchasable false: do not offer a checkout for it. Price and credit amount are server-side values; a checkout takes only the pack id.

Input

Returns 200 OK

Errors 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.billing.listCreditPackages();
console.log(result);

pd.billing.getCredits(input, init?)

Wallet balance, reserved and available

GET /api/workspaces/{workspaceId}/credits

Requires credits.read. available is balance less reserved. planBalance is the part of the balance the plan granted this period: it is spent first and expires at renewal, at planPeriodEnd (null unless the subscription is active or trialing). reservations lists the 50 most recent holds of any status, newest first.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.billing.getCredits({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.billing.adjustCredits(input, init?)

Adjust a wallet by hand

POST /api/workspaces/{workspaceId}/credits/adjust

Requires credits.adjust, which only the Owner role holds by default. A positive amount adds credits and a negative one removes them; either way a manual_adjustment row is appended to the ledger and the balance is never edited in place. A deduction is checked against the available credits (not the total balance) and answers 409 if it is larger. It also lowers planBalance when the balance falls below it. Records a credits.adjusted audit entry with the amount, the reason and the balance after. Returns the wallet as it stands afterwards.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.billing.adjustCredits({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  body: {
    amount: 1,
    reason: "example",
  },
});
console.log(result);

pd.billing.listPlans(init?)

The plans on offer

GET /api/plans

Public: needs no session. Returns the active plans in display order, the free plan included, with each plan's monthly credit grant, limits, monthly price and yearly price (yearlyPriceCents, two months free). It also returns the credit packs on sale, the credits a new account is granted at sign-up, and what an all-defaults article costs, so a pricing page can turn credits into a number of articles. A plan with purchasable false cannot be subscribed to here.

Input

Returns 200 OK

Errors 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.billing.listPlans();
console.log(result);

pd.billing.getSubscription(input, init?)

The plan in force, the subscription, and its invoices

GET /api/workspaces/{workspaceId}/subscription

Requires billing.read. Stripe is the authority on the subscription: this answer mirrors what Stripe last reported, and the mirror changes only when a verified Stripe webhook arrives. plan is the plan whose terms apply, which is the free plan when the workspace never subscribed or its subscription status does not carry the plan. subscription is null if the workspace never subscribed. invoices lists the last 24 paid subscription invoices.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.billing.getSubscription({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.billing.startSubscriptionCheckout(input, init?)

Start a Stripe checkout for a plan

POST /api/workspaces/{workspaceId}/subscription/checkout

Requires credits.purchase. Opens a Stripe Checkout session in subscription mode and returns its URL with 201; the customer pays on Stripe's page. Nothing changes here until Stripe's webhook arrives: the subscription and the plan credits come from the paid invoice, never from the browser returning to successUrl. Only for a workspace without a live subscription; plan changes and cancellation go through POST /api/workspaces/{workspaceId}/subscription/portal. Answers 404 for an unknown or inactive plan; 400 for the free plan or a plan with no Stripe price for the requested interval; 409 when the workspace already has a subscription (any status except canceled or incomplete_expired) or an earlier checkout was just paid; 402 when billing is not configured. Opening a new checkout expires the workspace's earlier unpaid subscription checkout. A buyer who was on the waitlist and received the launch email gets 50% off the first invoice of a monthly plan automatically (once, within 30 days of that email); a Stripe failure while confirming it answers 402 instead of charging full price.

Input

Returns 201 Created

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.billing.startSubscriptionCheckout({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  body: {
    planId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  },
});
console.log(result);

pd.billing.openPortal(input, init?)

Open the Stripe billing portal

POST /api/workspaces/{workspaceId}/subscription/portal

Requires credits.purchase. Opens a Stripe billing portal session and returns its URL, where the customer changes plan, cancels or updates the card. Any change made there reaches this API by Stripe webhook, not through this call. The request body is optional. Answers 402 when billing is not configured.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.billing.openPortal({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.billing.startCheckout(input, init?)

Start a Stripe checkout for a credit pack

POST /api/workspaces/{workspaceId}/checkout

Requires credits.purchase. Opens a one-off Stripe Checkout session for the pack and returns its URL with 201, and records the checkout as pending (visible in GET /api/workspaces/{workspaceId}/payments). Credits are added only when Stripe's verified webhook confirms the payment: that appends a purchase ledger row and emits the credits.purchased webhook event, and arriving at successUrl adds nothing. Answers 404 for an unknown or inactive pack, 400 for a pack with no Stripe price, and 402 when billing is not configured.

Input

Returns 201 Created

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.billing.startCheckout({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  body: {
    creditPackageId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  },
});
console.log(result);