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

# listPlans

> Return the workspace's published billing plans with pricing and features.

export const ExpectedOutput = ({caption = "Expected output", children}) => <div className="gv-output">
    <div className="gv-output__label">
      <svg className="gv-output__icon" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
        <polyline points="15 10 20 15 15 20" />
        <path d="M4 4v7a4 4 0 0 0 4 4h12" />
      </svg>
      <span>{caption}</span>
    </div>
    <div className="gv-output__body">{children}</div>
  </div>;

export const ErrorTable = ({errors}) => <div className="gv-error-table" role="table" aria-label="Errors and fixes">
    <div className="gv-error-table__head" role="row">
      <span className="gv-error-table__col-head" role="columnheader">Error</span>
      <span className="gv-error-table__col-head" role="columnheader">Cause</span>
      <span className="gv-error-table__col-head" role="columnheader">Fix</span>
    </div>
    {errors.map((err, i) => <div className="gv-error-table__row" role="row" key={i}>
        <code className="gv-error-table__code" role="cell">{err.code}</code>
        <div className="gv-error-table__cause" role="cell">{err.cause}</div>
        <div className="gv-error-table__fix" role="cell">{err.fix}</div>
      </div>)}
  </div>;

export const Def = ({term, type, defaultValue, required, children}) => <>
    <dt className="gv-def-list__term">
      <span className="gv-def-list__name">{term}</span>
      {type && <span className="gv-def-list__type">{type}</span>}
      {required && <span className="gv-def-list__required">required</span>}
      {defaultValue !== undefined && <span className="gv-def-list__default">
          default <code>{defaultValue}</code>
        </span>}
    </dt>
    <dd className="gv-def-list__description">{children}</dd>
  </>;

export const DefList = ({children}) => <dl className="gv-def-list">{children}</dl>;

export const ArrowItem = ({children}) => <li className="gv-arrow-item">
    <span className="gv-arrow-item__arrow" aria-hidden="true">{"↳︎"}</span>
    <span className="gv-arrow-item__content">{children}</span>
  </li>;

export const ArrowList = ({children}) => <ul className="gv-arrow-list">{children}</ul>;

export const Eyebrow = ({label, tone = "default"}) => <div className={`gv-eyebrow gv-eyebrow--${tone}`}>
    <span className="gv-eyebrow__bar" aria-hidden="true" />
    <span className="gv-eyebrow__label">{label}</span>
  </div>;

<Eyebrow label="CAPABILITY" />

`listPlans` returns every published billing plan for the workspace — IDs, prices, billing intervals, currencies, and feature lists. It is the data source for pricing pages and plan-selection UI: fetch once, bind the result to a `FeaturesGrid` or custom pricing block. Plan definitions live in the workspace's billing config rather than in code, so editors can publish new tiers without redeploying the page. By the end of this page you can wire a pricing block to live plan data and pass a chosen plan's `id` into [`collectPayment`](/capabilities/collect-payment).

## Invoke from a block

Bind a block's `data_source` to `listPlans` and the block populates from live plan data:

```json features-grid.json theme={null}
{
  "block": "FeaturesGrid",
  "props": {
    "data_source": {
      "capability": "listPlans"
    },
    "columns": 3
  }
}
```

`listPlans` takes no arguments. Each invocation returns the current published set — newly added plans appear on the next page load.

## Inputs

`listPlans` accepts no arguments. Pass an empty object or omit `args`.

## Outputs

<DefList>
  <Def term="plans" type="Plan[]">
    Ordered list of all published billing plans for this workspace. Each `Plan` carries the fields below.
  </Def>
</DefList>

### `Plan` fields

<DefList>
  <Def term="id" type="string">
    Stable plan identifier. Pass this as `plan_id` to [`collectPayment`](/capabilities/collect-payment).
  </Def>

  <Def term="name" type="string">Human-readable plan name, e.g. `"Pro Monthly"`.</Def>
  <Def term="description" type="string">Optional short description of what the plan includes.</Def>
  <Def term="price_cents" type="number">Price in the smallest currency unit. `4900` means \$49.00 USD.</Def>
  <Def term="currency" type="string">ISO 4217 currency code, e.g. `"usd"`.</Def>
  <Def term="interval" type="&#x22;month&#x22; | &#x22;year&#x22; | &#x22;one_time&#x22;">Billing cadence for this plan.</Def>
  <Def term="features" type="string[]">Marketing feature strings shown on pricing UI, e.g. `["Unlimited pages", "Custom domain"]`.</Def>
</DefList>

<ExpectedOutput caption="Example response">
  ```json theme={null}
  {
    "plans": [
      {
        "id": "plan_pro_monthly",
        "name": "Pro Monthly",
        "description": "Everything in Starter, plus custom domains.",
        "price_cents": 4900,
        "currency": "usd",
        "interval": "month",
        "features": ["Unlimited pages", "Custom domain"]
      }
    ]
  }
  ```
</ExpectedOutput>

## Provisioning

At least one plan must be defined in the workspace's billing configuration before `listPlans` returns a non-empty array. Plans are created and published in the Builder's billing settings or via the [Monetization API](/api-reference/resources/monetization).

## Error codes

<ErrorTable
  errors={[
{
  code: "invalid_input",
  cause: "The call envelope itself is malformed. `listPlans` takes no args, so this is rare in practice.",
  fix: "Pass an empty `args` object, or omit `args` entirely.",
},
]}
/>

Every error returns the standard envelope:

<ExpectedOutput caption="Error envelope">
  ```json error-envelope.json theme={null}
  {
    "ok": false,
    "error": {
      "code": "invalid_input",
      "message": "Invalid invocation envelope.",
      "details": {}
    }
  }
  ```
</ExpectedOutput>

## Related

<Columns cols={2}>
  <Card title="collectPayment" icon="credit-card" href="/capabilities/collect-payment">
    Open a Stripe Checkout session for a plan returned by `listPlans`.
  </Card>

  <Card title="Accept payments guide" icon="credit-card" href="/guides/accept-payments">
    End-to-end walkthrough from plan setup to a working checkout button.
  </Card>
</Columns>