Billing and credits

The plan, checkout and billing portal sessions, plan changes and AI credits.

Set up the SDK client used in the examples

API key or Dashboard session:

import { UpVoiced } from '@upvoiced/sdk';

const apiKey = process.env['UPVOICED_API_KEY']; // uv_live_… (Settings → API keys)
const workspace = process.env['UPVOICED_WORKSPACE_ID']; // sent as X-Workspace
if (!apiKey || !workspace) throw new Error('Set UPVOICED_API_KEY and UPVOICED_WORKSPACE_ID.');
const upvoiced = new UpVoiced({ apiKey, workspace });

curl examples read $UPVOICED_API_KEY and $UPVOICED_WORKSPACE_IDfrom your shell. MCP examples are the tools/call request an MCP client sends to the MCP server with the same API key.

GET`/v1/billing`

Plan, status, entitlements, usage and credits for upsell UI (any member)

Authentication: API key or Dashboard session; API key scope read
Operation id: getBilling

Headers
Name	Type	Required
`x-workspace`	`string (uuid)`	Yes

Response 200: 48 fields

Response 200 (application/json)
Name	Type	Required
`plan`	`"free" \| "starter" \| "growth" \| "business"`	Yes
`subscribed_plan`	`"free" \| "starter" \| "growth" \| "business"`	Yes
`interval`	`"month" \| "year"`	Yes
`status`	`"active" \| "trialing" \| "past_due" \| "paused" \| "canceled"`	Yes
`current_period_end`	`string (date-time) \| null`	Yes
`cancel_at_period_end`	`boolean`	Yes
`scheduled_change`	`object \| null`	Yes
`scheduled_change.plan`	`"free" \| "starter" \| "growth" \| "business"`	Yes
`scheduled_change.interval`	`"month" \| "year"`	Yes
`payment_failed`	`boolean`	Yes
`has_billing_account`	`boolean`	Yes
`entitlements`	`object`	Yes
`entitlements.boards.max`	`integer \| null`value 0–1000000000	Yes
`entitlements.posts.active_max`	`integer \| null`value 0–1000000000	Yes
`entitlements.members.max`	`integer \| null`value 0–1000000000	Yes
`entitlements.surveys.active_max`	`integer \| null`value 0–1000000000	Yes
`entitlements.testimonials.max`	`integer \| null`value 0–1000000000	Yes
`entitlements.video_testimonials`	`boolean`	Yes
`entitlements.walls.max`	`integer \| null`value 0–1000000000	Yes
`entitlements.powered_by.removable`	`boolean`	Yes
`entitlements.custom_domain`	`boolean`	Yes
`entitlements.custom_css`	`boolean`	Yes
`entitlements.integrations.slack_discord`	`boolean`	Yes
`entitlements.api.enabled`	`boolean`	Yes
`entitlements.api.access`	`"read_only" \| "read_write"`	Yes
`entitlements.api.keys_max`	`integer \| null`value 0–1000000000	Yes
`entitlements.mcp.enabled`	`boolean`	Yes
`entitlements.mcp.access`	`"read_only" \| "read_write"`	Yes
`entitlements.webhooks.max`	`integer \| null`value 0–1000000000	Yes
`entitlements.ai.credits_monthly`	`integer`value ≥ 0	Yes
`entitlements.end_user_sso`	`boolean`	Yes
`entitlements.audit_log`	`boolean`	Yes
`entitlements.private_boards`	`boolean`	Yes
`entitlements.email_recipients_monthly`	`integer \| null`value 0–1000000000	Yes
`entitlements.support`	`"community" \| "email" \| "priority_email" \| "priority_onboarding"`	Yes
`usage`	`object`	Yes
`usage.members`	`integer`value ≥ 0	Yes
`usage.boards`	`integer`value ≥ 0	Yes
`usage.active_posts`	`integer`value ≥ 0	Yes
`restrictions`	`object`	Yes
`restrictions.read_only_board_ids`	`array of string (uuid)`	Yes
`restrictions.board_selection`	`"default" \| "operator"`	Yes
`restrictions.new_posts_blocked`	`boolean`	Yes
`credits`	`object`	Yes
`credits.balance`	`integer`value ≥ 0	Yes
`credits.expiring`	`integer`value ≥ 0	Yes
`credits.expires_at`	`string (date-time) \| null`	Yes
`credits.low`	`boolean`	Yes

Errors: 400, 401, 403, 404, 409, 413, 422, 429, 500, 503, all in the standard error shape.

curl

curl 'https://api.upvoiced.com/v1/billing' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID"

TypeScript SDK

const data = await upvoiced.get('/v1/billing');

MCP

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_usage",
    "arguments": {
      "workspace": "0190f5e2-4c1d-7a3b-8c2d-5e6f7a8b9c0d"
    }
  }
}

Tool get_usage.

POST`/v1/billing/checkout`

Create a server-controlled Paddle transaction for a plan (owner)

Authentication: API key or Dashboard session; API key scope admin
Operation id: createCheckout
Idempotency: Send an Idempotency-Key to make retries safe.

Headers
Name	Type	Required
`x-workspace`	`string (uuid)`	Yes
`idempotency-key`	`string`pattern ^[A-Za-z0-9_.:-]{8,128}$	No

Request body (JSON)
Name	Type	Required
`plan`	`"starter" \| "growth" \| "business"`	Yes
`interval`	`"month" \| "year"`	Yes

Response 201: 1 fields

Response 201 (application/json)
Name	Type	Required
`transaction_id`	`string`pattern ^txn_[a-z\d]{26}$	Yes

Errors: 400, 401, 403, 404, 409, 413, 422, 429, 500, 503, all in the standard error shape.

curl

curl -X POST 'https://api.upvoiced.com/v1/billing/checkout' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "plan": "starter",
  "interval": "month"
}'

TypeScript SDK

const data = await upvoiced.post('/v1/billing/checkout', { body: { plan: 'starter', interval: 'month' } });

MCP

No MCP tool for this operation. The MCP server covers the everyday reads and writes.

POST`/v1/billing/portal`

Paddle customer portal session URL (owner)

Authentication: API key or Dashboard session; API key scope admin
Operation id: createBillingPortalSession
Idempotency: Send an Idempotency-Key to make retries safe.

Headers
Name	Type	Required
`x-workspace`	`string (uuid)`	Yes
`idempotency-key`	`string`pattern ^[A-Za-z0-9_.:-]{8,128}$	No

Response 200: 2 fields

Response 200 (application/json)
Name	Type	Required
`url`	`string (uri)`	Yes
`update_payment_method_url`	`string (uri) \| null`	Yes

Errors: 400, 401, 403, 404, 409, 413, 422, 429, 500, 503, all in the standard error shape.

curl

curl -X POST 'https://api.upvoiced.com/v1/billing/portal' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

TypeScript SDK

const data = await upvoiced.post('/v1/billing/portal', { body: {} });

MCP

No MCP tool for this operation. The MCP server covers the everyday reads and writes.

POST`/v1/billing/change`

Change plan/interval: upgrades prorated now, downgrades next period (owner)

Authentication: API key or Dashboard session; API key scope admin
Operation id: changePlan
Idempotency: Send an Idempotency-Key to make retries safe.

Headers
Name	Type	Required
`x-workspace`	`string (uuid)`	Yes
`idempotency-key`	`string`pattern ^[A-Za-z0-9_.:-]{8,128}$	No

Request body (JSON)
Name	Type	Required
`plan`	`"starter" \| "growth" \| "business"`	Yes
`interval`	`"month" \| "year"`	Yes

Response 200: 3 fields

Response 200 (application/json)
Name	Type	Required
`effective`	`"immediately" \| "next_billing_period"`	Yes
`plan`	`"starter" \| "growth" \| "business"`	Yes
`interval`	`"month" \| "year"`	Yes

Errors: 400, 401, 403, 404, 409, 413, 422, 429, 500, 503, all in the standard error shape.

curl

curl -X POST 'https://api.upvoiced.com/v1/billing/change' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "plan": "starter",
  "interval": "month"
}'

TypeScript SDK

const data = await upvoiced.post('/v1/billing/change', { body: { plan: 'starter', interval: 'month' } });

MCP

No MCP tool for this operation. The MCP server covers the everyday reads and writes.

POST`/v1/billing/cancel`

Cancel at the end of the billing period; data is kept (owner)

Authentication: API key or Dashboard session; API key scope admin
Operation id: cancelSubscription
Idempotency: Send an Idempotency-Key to make retries safe.

Headers
Name	Type	Required
`x-workspace`	`string (uuid)`	Yes
`idempotency-key`	`string`pattern ^[A-Za-z0-9_.:-]{8,128}$	No

Response 200: 2 fields

Response 200 (application/json)
Name	Type	Required
`cancel_at_period_end`	`boolean`	Yes
`current_period_end`	`string (date-time) \| null`	Yes

Errors: 400, 401, 403, 404, 409, 413, 422, 429, 500, 503, all in the standard error shape.

curl

curl -X POST 'https://api.upvoiced.com/v1/billing/cancel' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

TypeScript SDK

const data = await upvoiced.post('/v1/billing/cancel', { body: {} });

MCP

No MCP tool for this operation. The MCP server covers the everyday reads and writes.

POST`/v1/billing/resume`

Remove a scheduled cancellation (owner)

Authentication: API key or Dashboard session; API key scope admin
Operation id: resumeSubscription
Idempotency: Send an Idempotency-Key to make retries safe.

Headers
Name	Type	Required
`x-workspace`	`string (uuid)`	Yes
`idempotency-key`	`string`pattern ^[A-Za-z0-9_.:-]{8,128}$	No

Response 200: 2 fields

Response 200 (application/json)
Name	Type	Required
`cancel_at_period_end`	`boolean`	Yes
`current_period_end`	`string (date-time) \| null`	Yes

Errors: 400, 401, 403, 404, 409, 413, 422, 429, 500, 503, all in the standard error shape.

curl

curl -X POST 'https://api.upvoiced.com/v1/billing/resume' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

TypeScript SDK

const data = await upvoiced.post('/v1/billing/resume', { body: {} });

MCP

No MCP tool for this operation. The MCP server covers the everyday reads and writes.

GET`/v1/billing/credits`

AI credit balance and recent ledger entries (any member)

Authentication: API key or Dashboard session; API key scope read
Operation id: getCredits

Headers
Name	Type	Required
`x-workspace`	`string (uuid)`	Yes

Response 200: 10 fields

Response 200 (application/json)
Name	Type	Required
`credits`	`object`	Yes
`credits.balance`	`integer`value ≥ 0	Yes
`credits.expiring`	`integer`value ≥ 0	Yes
`credits.expires_at`	`string (date-time) \| null`	Yes
`credits.low`	`boolean`	Yes
`entries`	`array of object`	Yes
`entries[].delta`	`integer`	Yes
`entries[].reason`	`"plan_grant" \| "purchase" \| "consume" \| "refund" \| "adjust" \| "expire"`	Yes
`entries[].balance_after`	`integer`value ≥ 0	Yes
`entries[].created_at`	`string (date-time)`	Yes

Errors: 400, 401, 403, 404, 409, 413, 422, 429, 500, 503, all in the standard error shape.

curl

curl 'https://api.upvoiced.com/v1/billing/credits' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID"

TypeScript SDK

const data = await upvoiced.get('/v1/billing/credits');

MCP

No MCP tool for this operation. The MCP server covers the everyday reads and writes.

POST`/v1/billing/credits/checkout`

Create a Paddle transaction for an AI credit pack (owner/admin)

Authentication: API key or Dashboard session; API key scope admin
Operation id: createCreditsCheckout
Idempotency: Send an Idempotency-Key to make retries safe.

Headers
Name	Type	Required
`x-workspace`	`string (uuid)`	Yes
`idempotency-key`	`string`pattern ^[A-Za-z0-9_.:-]{8,128}$	No

Request body (JSON)
Name	Type	Required
`pack`	`500 \| 2500 \| 10000`	Yes

Response 201: 1 fields

Response 201 (application/json)
Name	Type	Required
`transaction_id`	`string`pattern ^txn_[a-z\d]{26}$	Yes

Errors: 400, 401, 403, 404, 409, 413, 422, 429, 500, 503, all in the standard error shape.

curl

curl -X POST 'https://api.upvoiced.com/v1/billing/credits/checkout' \
  -H "Authorization: Bearer $UPVOICED_API_KEY" \
  -H "X-Workspace: $UPVOICED_WORKSPACE_ID" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "pack": 500
}'

TypeScript SDK

const data = await upvoiced.post('/v1/billing/credits/checkout', { body: { pack: 500 } });

MCP

No MCP tool for this operation. The MCP server covers the everyday reads and writes.

Billing and credits

GET/v1/billing

POST/v1/billing/checkout

POST/v1/billing/portal

POST/v1/billing/change

POST/v1/billing/cancel

POST/v1/billing/resume

GET/v1/billing/credits

POST/v1/billing/credits/checkout

GET`/v1/billing`

POST`/v1/billing/checkout`

POST`/v1/billing/portal`

POST`/v1/billing/change`

POST`/v1/billing/cancel`

POST`/v1/billing/resume`

GET`/v1/billing/credits`

POST`/v1/billing/credits/checkout`