---
title: "Generate a checkout link"
method: POST
path: "/api/payments/checkout-link"
tags: ["Account"]
---

# Generate a checkout link

`POST /api/payments/checkout-link`

## Request

- Base URL: `https://clearlist.me`
- URL: `https://clearlist.me/api/payments/checkout-link`
- Auth: one of:
  - API key in header `X-ClearList-API-Key`
  - OAuth 2 (authorization code, authorization URL `https://clearlist.me/oauth/authorize`, token URL `https://clearlist.me/api/oauth/token`, scopes: `write`)

Returns a Stripe checkout URL for the requested plan. Send the URL to the user to pay in a browser; poll /api/payments/status to confirm. Naturally idempotent: no record is created; retries return the same payment link.

## Request body

- object
  - `plan` 'sale_pass' | 'big_move' | 'move_extension' | 'garage_extension', required

## Response `200`

Checkout link — or `already_paid`. When the account already holds an equal-or-higher active plan, the 200 carries `data.already_paid: true` with `plan`, `expires_at` and a human-readable `message` instead of a link; do NOT send the user to checkout in that case. Upgrades (sale_pass → big_move) still return a link.

- object
  - `success` boolean
  - `data` object
    - `checkout_url` string, uri: Stripe-hosted checkout URL. Absent when already_paid is true.
    - `already_paid` boolean: Present and true only when no link was issued because the current plan already covers the request.
    - `plan` string
    - `plan_name` string
    - `items_limit` number
    - `duration_days` number
    - `expires_at` string, date-time: Only on already_paid responses.
    - `suggested_action` string: Only on already_paid responses, when a time extension is available. Currently always "extend".
    - `suggested_sku` 'move_extension' | 'garage_extension': Only on already_paid responses. Call this endpoint again with plan set to this value to get a checkout link for 30 more days at the same item limit.
    - `suggested_price_usd` number: Price of suggested_sku in USD.
    - `message` string

## Other responses

- `400`: Invalid or missing parameters.
- `401`: Missing or invalid API key.
- `429`: Too many requests.

---

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