---
title: "Buy a per-project subscription"
method: POST
path: "/v1/subscriptions"
tags: ["Billing"]
---

# Buy a per-project subscription

`POST /v1/subscriptions`

## Request

- Base URL: `https://serp-agent.com`
- URL: `https://serp-agent.com/v1/subscriptions`
- Auth: HTTP bearer

Creates a Creem checkout for a monthly subscription on ONE project — the same basic ($199) / pro ($299) products the dashboard sells. Returns `checkout_url`: surface it to your human, who completes payment in the browser (Creem is merchant of record; taxes at checkout). The project activates automatically via webhook on payment — poll GET /v1/subscription?project_id=... . Subscribed projects run audits/articles all-inclusive (no credit charges). Sandbox keys get 403 `sandbox_not_billable` (the trial is free by design). An already actively-subscribed project returns 409 `already_subscribed`.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `project_id` string, required
  - `plan_id` 'basic' | 'pro', required: basic = $199/mo, pro = $299/mo (see GET /v1/plans).

## Response `201`

Checkout created — hand `checkout_url` to a human to complete payment.

- SubscriptionCheckout: A pending subscription purchase. Hand checkout_url to a human; the project activates via webhook on payment.
  - `status` 'pending_payment', required
  - `checkout_url` string, uri, required: Hosted Creem checkout — a human completes payment here.
  - `project_id` string, required
  - `plan` 'basic' | 'pro', required
  - `note` string

## Other responses

- `400`: Malformed body or unknown plan_id. Code: `invalid_request`.
- `401`: Missing, malformed, unknown, revoked, or expired API key. Codes: `unauthorized`, `key_revoked`, `key_expired`.
- `403`: Sandbox keys cannot make purchases. Code: `sandbox_not_billable`.
- `404`: No such project on this account. Code: `not_found`.
- `409`: The project already has an active subscription. Code: `already_subscribed`.
- `429`: Rate limit exceeded (600 requests/minute per API key). Honor `Retry-After`.
- `503`: Billing for this plan is not configured on the server yet. Code: `billing_not_configured`.

---

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