<!-- Markdown twin of https://pixelvault.dev/docs/api/billing/ -->

[API reference](/docs/api/)

# 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.

-   POST [Start a paid-plan checkout](#start_checkout)
-   POST [Open the billing portal](#open_billing_portal)

## 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`](/docs/api/usage/#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`](/docs/api/billing/#open_billing_portal). Limited to 10 requests per hour per account. For prices and what cancelling does, see [Billing & subscriptions](https://pixelvault.dev/docs/billing/).

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

-   200
    
    A Stripe Checkout URL to open in a browser
    
-   400
    
    [`invalid_plan`](/docs/errors/#invalid_plan): `plan` must be `starter` or `pro`.
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): missing Bearer token, or an invalid or expired dashboard token. [`invalid_api_key`](/docs/errors/#invalid_api_key): unknown or revoked key.
    
-   403
    
    [`email_not_verified`](/docs/errors/#email_not_verified): verify the email before upgrading. [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): use a secret key. [`test_key_forbidden`](/docs/errors/#test_key_forbidden): use a live key. [`account_suspended`](/docs/errors/#account_suspended): the key's account is suspended.
    
-   404
    
    [`not_found`](/docs/errors/#not_found): the account no longer exists.
    
-   409
    
    [`already_subscribed`](/docs/errors/#already_subscribed): a subscription exists; use [`open_billing_portal`](/docs/api/billing/#open_billing_portal).
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 10 billing requests per hour for the account. Honour `Retry-After`.
    
-   502
    
    [`billing_error`](/docs/errors/#billing_error): the Stripe call failed; retry shortly.
    
-   503
    
    [`billing_unavailable`](/docs/errors/#billing_unavailable): paid plans (or that plan) are not available.
    

Request

curlNode.jsPython

```
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

-   200
    
    A Stripe customer-portal URL to open in a browser
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): missing Bearer token, or an invalid or expired dashboard token. [`invalid_api_key`](/docs/errors/#invalid_api_key): unknown or revoked key.
    
-   403
    
    [`publishable_key_forbidden`](/docs/errors/#publishable_key_forbidden): use a secret key. [`test_key_forbidden`](/docs/errors/#test_key_forbidden): use a live key. [`account_suspended`](/docs/errors/#account_suspended): the key's account is suspended.
    
-   404
    
    [`no_subscription`](/docs/errors/#no_subscription): no billing history yet; start with [`start_checkout`](/docs/api/billing/#start_checkout). [`not_found`](/docs/errors/#not_found): the account no longer exists.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#rate_limit_exceeded): more than 10 billing requests per hour for the account. Honour `Retry-After`.
    
-   502
    
    [`billing_error`](/docs/errors/#billing_error): the Stripe call failed; retry shortly.
    
-   503
    
    [`billing_unavailable`](/docs/errors/#billing_unavailable): billing is not enabled.
    

Request

curlNode.jsPython

```
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"
}
```
