---
title: "Purchase Playbook"
method: POST
path: "/api/v1/playbooks/{playbook_id}/purchase"
tags: ["playbooks"]
---

# Purchase Playbook

`POST /api/v1/playbooks/{playbook_id}/purchase`

## Request

- Base URL: `https://api.badgeia.com`
- URL: `https://api.badgeia.com/api/v1/playbooks/{playbook_id}/purchase`
- Auth: none declared

Hire a paid public playbook through Stripe Connect. This endpoint is
fail-closed: without both billing authorization and a configured Stripe key,
it returns an explicit 503 before creating a purchase or clone.

Money is INT cents everywhere. Platform fee is computed via integer math so
reconciliation is exact: `fee + earnings == price_paid`.

## Path parameters

- `playbook_id` string, uuid, required

## Request body

- PlaybookPurchaseCreate: Purchase ("hire") a paid public playbook. The buyer is the authenticated user; `target_agent_id` is the agent in the buyer's roster that should receive the cloned playbook. In sandbox mode (MARKETPLACE_ENABLED=true, no Stripe), the purchase is recorded synchronously and the cloned playbook is minted in the same transaction.
  - `target_agent_id` string, uuid, required: Agent in the buyer's roster to receive the cloned playbook.

## Response `200`

Successful Response

- PlaybookCheckoutRead: Response for the LIVE charge path of POST /playbooks/{id}/purchase. Charge-first / deliver-on-confirm (F-01 Increment 2): no clone exists yet, so this deliberately carries NO clone field — the frontend redirects the buyer to `checkout_url` and the clone is minted by the webhook on payment confirmation. Returned with HTTP 200 (vs the lean-v1 fallback's 201 + PlaybookPurchaseRead), so the frontend branches on the response shape, not just the status code.
  - `checkout_url` string, required: Stripe-hosted Checkout Session URL to redirect to.
  - `purchase_id` string, uuid, required: The AWAITING_PAYMENT purchase row id.
  - `status` string: Always 'awaiting_payment' on this path.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/badgeia/apis/badge.md) · [All operations](https://skmtc.dev/badgeia/apis/badge/llms.txt) · [OpenAPI document](https://skmtc.dev/badgeia/apis/badge/revisions/7e7f7fee8b77?raw)