# Plans and billing for agents

> How agents show plans, start or change a plan, buy packs and handle limits over the Xholic API, MCP and CLI. Every payment finishes with the person on a Xholic or Dodo page.

Source: https://docs.xholic.ai/api/plans-and-billing/

Every plan includes every feature and unlimited API, MCP and CLI calls; plans differ in limits. New accounts get a 7-day free trial with no card.

| Plan | Monthly / quarterly / yearly | Posts a month | AI credits a month | Active Workers | Lead agents | X accounts |
| --- | --- | --- | --- | --- | --- | --- |
| Pro | $19 / $50.67 / $171 | 150 | 500 | 4 | 1 | 1 |
| Max | $29 / $77.33 / $261 | 300 | 1000 | 10 | 3 | 3 |
| Ultra | $99 / $264 / $891 | 800 | 2500 | 25 | 8 | 5 |

## Starting and changing plans

Agents never charge a card. Each action returns a link; the person opens it and pays or confirms on a page that shows the exact amount.

- `get_plans`: every plan, its prices and limits, the current plan and what each adds over it.
- `start_plan` (`plan`, optional `interval`): from a trial or an ended plan, a link that opens checkout for that plan; it starts as soon as it's paid. On a paid plan, a higher plan (or the same plan billed for longer) applies now, prorated; a lower plan or shorter billing switches at the end of the current billing period, and nothing is charged today.
- `buy_pack` (`pack`): a link to buy AI credits, post credits or automated DMs. Packs never expire, are used after the plan's monthly allowance and need a paid plan.
- `manage_billing` (`action`): links to cancel, resume, update the card, edit billing details or see invoices.
- `get_billing`: the plan right now. Call it after the person says they paid, before saying anything started.

## When a limit is reached

A refusal caused by a plan or pack limit carries what fixes it in `error.details.upgrade`, and one sentence with the link is added to the message:

```json
{
  "code": "QUOTA_EXCEEDED",
  "message": "Monthly posting limit reached. Pro's posts are used up: a 100 post credits pack is $4 and never expires, or Max includes 300 posts a month for $29/month. Buy it here: https://app.xholic.ai/billing/manage?pack=posts_100",
  "details": {
    "upgrade": {
      "reason": "posts",
      "plan": "pro",
      "options": [
        {
          "kind": "pack",
          "packId": "posts_100",
          "label": "100 post credits",
          "priceUsd": 4
        },
        {
          "kind": "plan",
          "plan": "max",
          "monthlyPriceUsd": 29,
          "gives": "300 posts a month"
        }
      ],
      "url": "https://app.xholic.ai/billing/manage?pack=posts_100",
      "message": "Pro's posts are used up: a 100 post credits pack is $4 and never expires, or Max includes 300 posts a month for $29/month. Buy it here: https://app.xholic.ai/billing/manage?pack=posts_100",
      "offer": "A 100 post credits pack is $4 and never expires, or Max includes 300 posts a month for $29/month. Buy it here: https://app.xholic.ai/billing/manage?pack=posts_100"
    }
  }
}
```

- On the trial it offers Pro; packs need a paid plan.
- On Pro and Max, posts, DMs and AI credits offer the smallest pack first, then the next plan. Workers, lead agents, products, X lookups and imports offer the next plan.
- On Ultra, a pack when one helps; otherwise `support: true` and `contact_support` reaches the Xholic team.
- An ended trial or plan returns `SUBSCRIPTION_REQUIRED` with the plans link.
- Per-minute rate limits name the next plan's limits once a day.

A successful result can carry a one-line `notice`: when the trial has two days left, or when most of the period's posts or AI credits are used. At most one notice a day per account.

## Opening the app

`open_in_xholic` returns a link to a page of the app, such as the queue, one post, analytics, a contact list or settings, opened as the chosen X account. `connect_account`, `sharing` and `security` open the screens where the person connects X accounts, shares access or signs out sessions.
