---
title: "Create a checkout for an organization: a Stripe session, or a Lightning invoice (rail: lightning)"
method: POST
path: "/orgs/v1/{org_id}/checkouts"
tags: ["Billing"]
---

# Create a checkout for an organization: a Stripe session, or a Lightning invoice (rail: lightning)

`POST /orgs/v1/{org_id}/checkouts`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/orgs/v1/{org_id}/checkouts`
- Auth: one of:
  - API key in header `SIGN-IN-WITH-X`
  - API key in header `x-admin-key`

Create a Stripe Checkout session for an organization. The product field selects the checkout kind: balance_topup credits the org allowance, tier starts/renews/upgrades a tier lease, and email_pack buys 10,000 email credits. Requires admin key or an org role of billing or higher. Optional success_url/cancel_url must use trusted Run402 or localhost origins.

## Path parameters

- `org_id` string, uuid, required

## Request body

- union
  - object
    - `product` 'balance_topup', required
    - `amount_usd_micros` integer, required: Amount in micro-USD
    - `success_url` string, uri: Optional trusted Run402 or localhost return URL
    - `cancel_url` string, uri: Optional trusted Run402 or localhost return URL
  - object
    - `product` 'tier', required
    - `tier` 'prototype' | 'hobby' | 'team', required
    - `success_url` string, uri: Optional trusted Run402 or localhost return URL
    - `cancel_url` string, uri: Optional trusted Run402 or localhost return URL
  - object
    - `product` 'email_pack', required
    - `success_url` string, uri: Optional trusted Run402 or localhost return URL
    - `cancel_url` string, uri: Optional trusted Run402 or localhost return URL
  - object: lightning-cash-topup: mint a bolt11 invoice through the configured hosted Lightning provider. No Stripe, no funds moved at creation; the USD value is fixed from a recorded rate at mint. Any active org member or a grant key holding a live grant on one of the org's projects may create one. Responds 201 with the LightningTopup (200 on an idempotent replay).
    - `product` 'balance_topup'
    - `rail` 'lightning', required
    - `amount_sats` integer, required: Whole satoshis

## Response `200`

Checkout session created

- object
  - `org_id` string, uuid, required
  - `product` 'balance_topup' | 'tier' | 'email_pack', required
  - `checkout_url` string, uri, required
  - `topup_id` string, required

## Other responses

- `201`: Lightning top-up created (rail: lightning): a pending bolt11 invoice with the quoted USD value
- `400`: Invalid product body, tier, amount, or return URL
- `401`: Missing or invalid auth
- `403`: Billing role required
- `404`: Organization not found

---

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