---
title: "Start a card top-up"
method: POST
path: "/v1/credits/checkout"
tags: ["Account"]
---

# Start a card top-up

`POST /v1/credits/checkout`

## Request

- Base URL: `https://api.placementapi.com`
- URL: `https://api.placementapi.com/v1/credits/checkout`
- Auth: HTTP bearer

Returns a Stripe Checkout URL. Credits are granted by the payment webhook when the payment clears, not by this response. Card only.

## Request body

- object
  - `amount_cents` integer, required: Cents, which is also credits ($50 to $100,000).
  - `save_card` boolean: Keep the card on file for auto-reload (recorded at Stripe as setup_future_usage).

## Response `200`

OK

- object
  - `checkout_url` string, nullable
  - `session_id` string
  - `amount_cents` integer
  - `credits` integer
  - `note` string

## Other responses

- `400`: Malformed request. `error` is `bad_request` (with a zod `detail`), `invalid_json`, or `unknown_parameter` / `unknown_field` (with `unknown[]` and `accepted[]`).
- `401`: Missing, malformed or revoked Bearer credential: `{ error: "unauthorized" }`.
- `403`: `insufficient_scope` when the key lacks the `order` scope; `customer_key_required` when the operator token is used where a customer must be attributable.
- `404`: `customer_not_found`.
- `503`: `server_misconfigured` when the store is not configured; `upstream_unfunded` when the measurement provider's prepaid balance is exhausted (fresh profiles, gap maps and SERPs pause; cached results and catalogue are unaffected); `upstream_unavailable` on a provider error; `payments_unavailable` when card payments are not configured.

---

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