> For the complete documentation index, see [llms.txt](https://docs.guayaba.run/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.guayaba.run/documentation/api-reference/billing.md).

# Billing

Subscription, tiers, and credits. Requires master key.

## Show billing info

> Returns current subscription and billing details. Requires a \*\*master key\*\*.<br>

```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Billing","description":"Subscription, tiers, and credits. Requires master key."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"Subscription":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"tier_slug":{"type":"string"},"status":{"type":"string","enum":["active","trialing","past_due","canceled","incomplete","incomplete_expired","unpaid","paused"]},"stripe_subscription_id":{"type":"string","nullable":true},"stripe_customer_id":{"type":"string","nullable":true},"started_at":{"type":"string","format":"date-time","nullable":true},"monthly_credits":{"type":"integer"},"current_period_start":{"type":"string","format":"date-time","nullable":true},"current_period_end":{"type":"string","format":"date-time","nullable":true},"trial_start":{"type":"string","format":"date-time","nullable":true},"trial_end":{"type":"string","format":"date-time","nullable":true},"cancel_at_period_end":{"type":"boolean","nullable":true},"cancel_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"tier":{"$ref":"#/components/schemas/Tier"}}},"Tier":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"monthly_credits":{"type":"integer"},"price":{"type":"number","format":"float"},"features":{"type":"array","nullable":true,"items":{"type":"string"}},"max_running_agents":{"type":"integer","nullable":true},"allowed_channels":{"type":"array","nullable":true,"items":{"type":"string"}},"can_buy_credit_packages":{"type":"boolean"},"trial_days":{"type":"integer"},"is_active":{"type":"boolean"},"sort_order":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"MasterKeyRequired":{"description":"Forbidden — Requires a master API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/billing":{"get":{"tags":["Billing"],"summary":"Show billing info","description":"Returns current subscription and billing details. Requires a **master key**.\n","responses":{"200":{"description":"Billing details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Subscription"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MasterKeyRequired"}}}}}}
```

## List subscription tiers

> Returns available subscription tiers and pricing. Requires a \*\*master key\*\*.<br>

```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Billing","description":"Subscription, tiers, and credits. Requires master key."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"Tier":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"monthly_credits":{"type":"integer"},"price":{"type":"number","format":"float"},"features":{"type":"array","nullable":true,"items":{"type":"string"}},"max_running_agents":{"type":"integer","nullable":true},"allowed_channels":{"type":"array","nullable":true,"items":{"type":"string"}},"can_buy_credit_packages":{"type":"boolean"},"trial_days":{"type":"integer"},"is_active":{"type":"boolean"},"sort_order":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"MasterKeyRequired":{"description":"Forbidden — Requires a master API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/billing/tiers":{"get":{"tags":["Billing"],"summary":"List subscription tiers","description":"Returns available subscription tiers and pricing. Requires a **master key**.\n","responses":{"200":{"description":"Subscription tiers","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Tier"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MasterKeyRequired"}}}}}}
```

## Get credits breakdown

> Returns detailed credits breakdown (subscription vs purchased). Requires a \*\*master key\*\*.<br>

```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Billing","description":"Subscription, tiers, and credits. Requires master key."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"CreditBreakdown":{"type":"object","properties":{"total_credits":{"type":"integer"},"subscription_credits":{"type":"integer"},"purchased_credits":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"MasterKeyRequired":{"description":"Forbidden — Requires a master API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/billing/credits":{"get":{"tags":["Billing"],"summary":"Get credits breakdown","description":"Returns detailed credits breakdown (subscription vs purchased). Requires a **master key**.\n","responses":{"200":{"description":"Credits breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/CreditBreakdown"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MasterKeyRequired"}}}}}}
```
