Billing
Start an upgrade or open the Stripe customer portal without a dashboard session. Both return a Stripe URL for a person to open; nothing is charged by the API call itself.
Start a paid-plan checkout
POST /v1/billing/checkout
Returns a Stripe Checkout URL for the chosen plan, so an agent can start an upgrade without a dashboard session. A person completes payment on that page; nothing is charged by the API call itself. The plan changes only after Stripe confirms payment, so poll get_usage for plan rather than assuming success.
Needs a live secret key (pv_live_) or a dashboard token; test and publishable keys get 403. Requires a verified email. If a subscription already exists, use open_billing_portal. Limited to 10 requests per hour per account. For prices and what cancelling does, see Billing & subscriptions.
The response is a bare { "url": … } object, not wrapped in data.
Authentication
API key, or a dashboard session token, sent as Authorization: Bearer <token>.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
plan | string | Required | Plan to subscribe to. |
promo | string | Optional | Optional Stripe promotion code to pre-apply. Unknown or malformed codes are ignored and the checkout page accepts a code instead. |
Responses
- 200
A Stripe Checkout URL to open in a browser
- 400
invalid_plan:planmust bestarterorpro. - 401
unauthorized: missing Bearer token, or an invalid or expired dashboard token.invalid_api_key: unknown or revoked key. - 403
email_not_verified: verify the email before upgrading.publishable_key_forbidden: use a secret key.test_key_forbidden: use a live key.account_suspended: the key's account is suspended. - 404
not_found: the account no longer exists. - 409
already_subscribed: a subscription exists; useopen_billing_portal. - 429
rate_limit_exceeded: more than 10 billing requests per hour for the account. HonourRetry-After. - 502
billing_error: the Stripe call failed; retry shortly. - 503
billing_unavailable: paid plans (or that plan) are not available.
curl -X POST https://api.pixelvault.dev/v1/billing/checkout \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"plan":"starter","promo":"LAUNCH20"}' {
"url": "https://checkout.stripe.com/c/pay/cs_live_a1b2c3"
} Open the billing portal
POST /v1/billing/portal
Returns a Stripe customer-portal URL to change plan, update payment details or cancel. Show the URL only to the account owner: the portal can cancel the subscription.
Needs a live secret key (pv_live_) or a dashboard token; test and publishable keys get 403. Limited to 10 requests per hour per account. The response is a bare { "url": … } object, not wrapped in data.
Authentication
API key, or a dashboard session token, sent as Authorization: Bearer <token>.
Responses
- 200
A Stripe customer-portal URL to open in a browser
- 401
unauthorized: missing Bearer token, or an invalid or expired dashboard token.invalid_api_key: unknown or revoked key. - 403
publishable_key_forbidden: use a secret key.test_key_forbidden: use a live key.account_suspended: the key's account is suspended. - 404
no_subscription: no billing history yet; start withstart_checkout.not_found: the account no longer exists. - 429
rate_limit_exceeded: more than 10 billing requests per hour for the account. HonourRetry-After. - 502
billing_error: the Stripe call failed; retry shortly. - 503
billing_unavailable: billing is not enabled.
curl -X POST https://api.pixelvault.dev/v1/billing/portal \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"url": "https://billing.stripe.com/p/session/live_a1b2c3"
}