Images Videos Audio Pricing Docs View as Markdown (Agent) Get started
Human Agent

API reference

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

application/json, required

Request body
Name Type Required Description
plan string Required

Plan to subscribe to.

One of: starter, pro

promo string Optional

Optional Stripe promotion code to pre-apply. Unknown or malformed codes are ignored and the checkout page accepts a code instead.

pattern ^[A-Za-z0-9_-]{3,40}$

Responses

Request
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"}'
Response 200
{
  "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

Request
curl -X POST https://api.pixelvault.dev/v1/billing/portal \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
Response 200
{
  "url": "https://billing.stripe.com/p/session/live_a1b2c3"
}