> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safeclose.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage subscriptions and billing with Stripe

> Start a Stripe Checkout session to subscribe your organization to a Safeclose plan, or open the Customer Portal to update payment details and manage invoices.

Safeclose uses Stripe to handle subscription billing for your organization. From the Safeclose UI — or directly through the API — you can start a Stripe Checkout session to select a plan, and open the Stripe Customer Portal to manage payment methods, view invoices, or cancel your subscription. When Stripe processes a payment or subscription change, Safeclose receives a webhook and updates your organization's billing status automatically.

<Info>
  You must have the **billing** permission in your organization to start checkout sessions or open the Customer Portal. Organization owners always have this permission. See [Organizations and billing](/guides/organizations-billing) for how to grant billing access to other members.
</Info>

## Available plans

| Plan       | Tier value   |
| ---------- | ------------ |
| Starter    | `STARTER`    |
| Pro        | `PRO`        |
| Enterprise | `ENTERPRISE` |

Your organization starts on the Free tier until a checkout is completed.

## Start a checkout session

`POST /api/billing/checkout-session` creates a Stripe Checkout session for the specified plan and returns a redirect URL. Send the user to that URL to complete payment.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://your-app.com/api/billing/checkout-session \
    -H "Cookie: <your-session-cookie>" \
    -H "Content-Type: application/json" \
    -d '{
      "orgId": "org_01example",
      "planTier": "PRO"
    }'
  ```

  ```json Response theme={null}
  {
    "url": "https://checkout.stripe.com/c/pay/cs_live_..."
  }
  ```
</CodeGroup>

**Request body:**

| Field      | Type   | Required | Description                                     |
| ---------- | ------ | -------- | ----------------------------------------------- |
| `orgId`    | string | Yes      | Your organization's ID.                         |
| `planTier` | string | Yes      | One of `"STARTER"`, `"PRO"`, or `"ENTERPRISE"`. |

Redirect the user to the returned `url`. After a successful payment, Stripe sends a webhook to Safeclose, which links your organization to the Stripe customer and activates the selected plan. The user is then redirected back to your billing page.

<Note>
  If the user cancels the checkout, they are redirected back to your billing page with no changes to your subscription.
</Note>

## Open the Customer Portal

`POST /api/billing/portal` opens the Stripe Customer Portal where your organization can update payment methods, download invoices, or cancel the subscription.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://your-app.com/api/billing/portal \
    -H "Cookie: <your-session-cookie>" \
    -H "Content-Type: application/json" \
    -d '{
      "orgId": "org_01example"
    }'
  ```

  ```json Response theme={null}
  {
    "url": "https://billing.stripe.com/session/..."
  }
  ```
</CodeGroup>

**Request body:**

| Field   | Type   | Required | Description             |
| ------- | ------ | -------- | ----------------------- |
| `orgId` | string | Yes      | Your organization's ID. |

Redirect the user to the returned `url`. Stripe handles the session and returns the user to your billing page when they are done.

## How billing status updates work

After a successful checkout or subscription change, Stripe sends a webhook event to Safeclose. Safeclose processes the following events automatically:

| Stripe event                    | What changes in Safeclose                                                               |
| ------------------------------- | --------------------------------------------------------------------------------------- |
| `checkout.session.completed`    | Your organization is linked to a Stripe customer and the selected plan tier is applied. |
| `customer.subscription.updated` | Subscription status and current period end date are refreshed.                          |
| `customer.subscription.deleted` | Your subscription is marked as canceled and your plan reverts to Free.                  |
| `invoice.paid`                  | Subscription status is confirmed as active.                                             |
| `invoice.payment_failed`        | Your billing account is flagged as past due.                                            |

You do not need to take any action for these updates — Safeclose handles them in the background.

<Tip>
  To see your current subscription status and billing history, go to **Organizations → your org → Billing** in Safeclose, or open the Customer Portal using the steps above.
</Tip>

## API summary

| Method | Path                            | Auth             | Permission | Description                                           |
| ------ | ------------------------------- | ---------------- | ---------- | ----------------------------------------------------- |
| `POST` | `/api/billing/checkout-session` | Session required | `billing`  | Creates a Stripe Checkout session for a plan upgrade. |
| `POST` | `/api/billing/portal`           | Session required | `billing`  | Returns a Stripe Customer Portal URL.                 |

## Related pages

<CardGroup cols={2}>
  <Card title="Organizations and billing" icon="building" href="/guides/organizations-billing">
    Learn how to manage org members, assign billing permissions, and view your plan.
  </Card>

  <Card title="Stripe webhook events" icon="webhook" href="/integrations/webhooks">
    Understand how Safeclose verifies and processes Stripe webhook events.
  </Card>
</CardGroup>