---
title: "Get a Stripe Checkout URL for the human to complete"
method: POST
path: "/api/v1/billing/checkout-url"
tags: ["Billing"]
---

# Get a Stripe Checkout URL for the human to complete

`POST /api/v1/billing/checkout-url`

## Request

- Base URL: `https://volunteerreminder.com`
- URL: `https://volunteerreminder.com/api/v1/billing/checkout-url`
- Auth: HTTP bearer

Create a Stripe-hosted Checkout session for a named plan/interval and return its URL for the ACCOUNT OWNER to open and pay — the agent never takes payment. Reuses the dashboard's session-creation logic, including the already-subscribed guard and idempotency key. Requires the `read` scope (this endpoint returns a URL and mutates no agent-managed data; the irreversible act, payment, stays with the human — agent-channel §3.4).

## Request body

- CheckoutUrlRequest
  - `plan` 'basic' | 'deluxe' | 'pro', required: The plan to subscribe to (the public plan ids from GET /pricing).
  - `interval` 'monthly' | 'annual': Billing interval. Defaults to monthly.

## Response `200`

A hosted Checkout URL for the human to complete payment.

- CheckoutUrlResponse
  - `checkout_url` string, required: A Stripe-hosted Checkout URL. Give this to the human to open and complete payment — the agent never takes payment itself.
  - `plan` string, required
  - `interval` 'monthly' | 'annual', required

## Other responses

- `400`: The request failed schema validation (`validation_error`). On the import endpoints, also when the text is UTF-16 (Excel "Unicode Text"; `unsupported_encoding`): resend it as CSV UTF-8.
- `401`: Missing or invalid API key.
- `403`: The API key lacks a scope required by this endpoint.
- `404`: The requested resource does not exist.
- `409`: The account already has an active subscription.
- `502`: Billing is temporarily unavailable (Stripe not configured/reachable).

---

[API](https://skmtc.dev/volunteerreminder/apis/volunteerreminder-api.md) · [All operations](https://skmtc.dev/volunteerreminder/apis/volunteerreminder-api/llms.txt) · [OpenAPI document](https://skmtc.dev/volunteerreminder/apis/volunteerreminder-api/revisions/f8e7e26ba96f?raw)