> ## Documentation Index
> Fetch the complete documentation index at: https://docs.priceos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage pricing tables with the API

Use a secret PriceOS API key to create and manage pricing-table releases. The API uses `productKey` and `stripePriceId`; it never requires internal PriceOS IDs.

## Release workflow

1. `POST /v1/pricing-tables` creates version 1 as a draft.
2. `POST /v1/pricing-tables/releases/{releaseId}/publish` makes that draft current.
3. `POST /v1/pricing-tables/releases/{releaseId}/duplicate` creates the next draft when you need a change.
4. Update the draft with `PUT /v1/pricing-tables/releases/{releaseId}`, then publish it.

Current and legacy releases are immutable. Existing active subscribers keep the release assigned to their Stripe subscription; new subscribers receive the current release.

## Create a table

```ts theme={null}
import { PriceOS } from "priceos";

const priceos = new PriceOS(process.env.PRICEOS_API_KEY!);

const draft = await priceos.pricingTables.create({
  name: "Marketing pricing",
  tableKey: "marketing-pricing",
  settings: {
    defaultView: "monthly",
    buttonShape: "pill",
  },
  config: {
    products: [
      { productKey: "starter", stripePriceId: "price_starter_monthly" },
      { productKey: "pro", stripePriceId: "price_pro_monthly" },
    ],
    productTitles: { pro: "Most popular" },
    display: { yearlyBadgeText: "Save 20%" },
  },
});

await priceos.pricingTables.publish(draft.id);
```

The management API supports every dashboard setting: plan titles and descriptions, CTA overrides, custom products, feature labels, display options, colors, typography, and product sliders. See the [API reference](/api-reference) for the complete schema.

## Build a custom UI

For any framework, use the public loader to receive the resolved table, plans, prices, features, customer state, and release ID:

```ts theme={null}
import { loadPricingTable } from "priceos";

const pricingTable = await loadPricingTable({
  pricingTableKey: "marketing-pricing",
  publishableKey: process.env.NEXT_PUBLIC_PRICEOS_PUBLISHABLE_KEY!,
  customerId: currentCustomerId,
});
```

React users can use `usePricingTable()` without rendering the PriceOS component. Send the selected product key, Stripe price ID, and `pricingTable.table.releaseId` to your authenticated server checkout route; the PriceOS Next.js helper returns the Stripe Checkout URL.