---
title: "Create or validate a hosted plan purchase choice"
method: POST
path: "/billing/purchase-choice"
tags: ["Billing"]
---

# Create or validate a hosted plan purchase choice

`POST /billing/purchase-choice`

## Request

- Base URL: `https://app.openpo.st/api/v1`
- URL: `https://app.openpo.st/api/v1/billing/purchase-choice`
- Auth: none required

Returns canonical plan, price, trial, payment, and expiry facts in an integrity-protected continuation token.

## Request body

- CreatePurchaseChoiceInputBody
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `billing_period` 'monthly' | 'annual', required: Canonical billing period
  - `plan_id` string, required: Canonical hosted plan ID: founder (Solo), team, or agency
  - `purchase_choice_token` string: Existing integrity-protected choice to validate against the supplied plan and period

## Response `200`

OK

- PurchaseChoiceResponse
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `billing_period` 'monthly' | 'annual', required: Canonical billing period
  - `card_required` boolean, required: Whether checkout requires a payment card for the trial
  - `catalog_version` string, required: Canonical plan catalogue revision bound to the choice
  - `due_today_usd` integer, required: Canonical USD amount due when the trial starts
  - `expires_at` string, date-time, required: When this purchase choice must be replaced
  - `list_price_usd` integer, required: Full-period canonical USD list price
  - `plan_id` string, required: Canonical hosted plan ID
  - `plan_name` string, required: Canonical hosted plan name
  - `token` string, required: Integrity-protected purchase choice continuation token
  - `trial_days` integer, required: Trial length in calendar days

## Other responses

- `400`: Bad Request
- `422`: Unprocessable Entity
- `500`: Internal Server Error
- `503`: Service Unavailable

---

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