---
title: "Buy ONE period of continuity under a mandate the instrument proves. Nothing renews."
method: POST
path: "/purchases"
---

# Buy ONE period of continuity under a mandate the instrument proves. Nothing renews.

`POST /purchases`

## Request

- Base URL: `https://forbiz.io/api/public/agent`
- URL: `https://forbiz.io/api/public/agent/purchases`
- Auth: HTTP bearer

THE PAYMENT TOKEN IS THE SPENDING AUTHORITY (1.50.0): any active identity of the workspace may call this — including a provisional credential on an unclaimed workspace — and no capability has to be granted first, because the human who granted the token's mandate already delegated the spending. Idempotency-Key is REQUIRED: without it the request is refused 400 IDEMPOTENCY_KEY_REQUIRED. The mandate (limit, currency, expiry) is read from the instrument at Stripe and never from this body. Omit instrument to reserve the purchase and pay it later with POST /purchases/{id}/pay. ACTIVATION IS NEVER WRITTEN BY THIS ROUTE: a successful charge answers 200 with status payment_received and activated false, and the signature-verified payment_intent.succeeded webhook activates the period a moment later — read GET /purchases/{id} to see it active. Refusals: ALREADY_COVERED when the period is already paid for, PURCHASE_ALREADY_OPEN when one purchase is already open, MANDATE_INSUFFICIENT with the recorded verdict when the instrument does not carry the amount, and 503 MANDATE_UNVERIFIED with retry_after_seconds when Stripe could not be asked at all (nothing is charged and the purchase stays open). Every refusal carries missing as a list of { code, detail } with code one of no_instrument, over_limit, wrong_currency, expired, deactivated, unverified.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `plan` string, required
  - `instrument` object
    - `kind` 'shared_payment_token'
    - `id` string

## Response `200`

Payment received; the webhook activates the period

- object

## Other responses

- `201`: Purchase created
- `208`: Idempotent replay of a previous request with the same Idempotency-Key. Nothing was applied again.
- `400`: Idempotency-Key missing, or the body is not usable
- `402`: The instrument does not carry this amount
- `409`: Already covered, or a purchase is already open
- `503`: The mandate could not be read; nothing was charged

---

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