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

# Proration Checkout

> Create a checkout session for a mid-cycle seat upgrade with proration.

When a tenant needs more seats mid-billing cycle, this endpoint calculates the prorated charge for the remaining days and creates a Stripe checkout session for that amount.

The actual capacity upgrade happens **after payment confirmation** via the Stripe webhook (`event_type: seat_proration`). For non-Stripe providers (Khalti, eSewa), an invoice is generated instead.

## Request Body

<ParamField body="externalTenantId" type="string" required>
  The external tenant/workspace ID from your application
</ParamField>

<ParamField body="newCapacity" type="integer" required>
  The new total seat count (must be greater than current `capacityUnits`)
</ParamField>

<ParamField body="planId" type="string">
  The plan ID to upgrade. Defaults to the tenant's current active plan.
</ParamField>

<ParamField body="successUrl" type="string">
  URL to redirect to after payment. Defaults to the org's configured success URL.
</ParamField>

<ParamField body="cancelUrl" type="string">
  URL to redirect to if the user cancels. Defaults to the org's configured cancel URL.
</ParamField>

## Authentication

Requires a **secret key** (`Authorization: Bearer sk_live_...`) or **service key** (`x-service-key` + `?orgId=`).

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.crovver.com/api/public/capacity/proration-checkout" \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "externalTenantId": "workspace_123",
      "newCapacity": 15,
      "successUrl": "https://app.com/settings?upgraded=1",
      "cancelUrl": "https://app.com/settings/seats"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Stripe checkout created theme={null}
  {
    "success": true,
    "data": {
      "prorationId": "uuid",
      "checkoutUrl": "https://checkout.stripe.com/pay/cs_...",
      "requiresPayment": true,
      "prorationAmount": 1750,
      "prorationDetails": {
        "description": "Prorated charge for 5 additional seats",
        "calculation": "5 seats × $1.00/seat × 17/30 days"
      },
      "message": "Checkout session created. Capacity will be upgraded after payment confirmation."
    }
  }
  ```

  ```json 200 Invoice generated (non-Stripe) theme={null}
  {
    "success": true,
    "data": {
      "prorationId": "uuid",
      "checkoutUrl": null,
      "requiresPayment": false,
      "prorationAmount": 1750,
      "message": "Invoice generated. Capacity will be updated after payment confirmation."
    }
  }
  ```
</ResponseExample>