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

# Customer Portal

> Redirect to the Stripe Customer Portal for subscription and billing management

This endpoint creates a Stripe Customer Portal session and redirects the user to manage their subscription, payment methods, and billing history. The portal is hosted by Stripe and provides a secure, self-service interface for customers.

## Authentication

<Note>
  This endpoint requires authentication. The user must be authenticated and
  associated with an organization that has a Stripe customer record.
</Note>

## Request

This endpoint does not require any request parameters. The organization is identified automatically from the authentication context.

## Response

<ResponseField name="redirect" type="HTTP 302 Redirect" required>
  On success, this endpoint performs an HTTP 302 redirect to the Stripe Customer
  Portal URL. The browser will automatically navigate to the Stripe-hosted
  portal page.
</ResponseField>

## Portal Features

The Stripe Customer Portal allows customers to:

| Feature                     | Description                                       |
| --------------------------- | ------------------------------------------------- |
| **Subscription Management** | View, upgrade, downgrade, or cancel subscriptions |
| **Payment Methods**         | Add, update, or remove payment methods            |
| **Billing History**         | View past invoices and payment history            |
| **Invoice Download**        | Download PDF invoices for accounting purposes     |

## Return URL

After the user completes their actions in the Customer Portal, they are redirected back to:

```
https://{host}/organization#/plans
```

This ensures a seamless return to the organization settings page within the application.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.lance.so/api/v1/operations/payment/customer-portal" \
    -H "Authorization: Bearer <token>" \
    -L
  ```

  ```javascript JavaScript theme={null}
  // Note: This endpoint redirects, so use it as a link or window.location
  window.location.href = "/api/v1/operations/payment/customer-portal";
  ```

  ```typescript TypeScript theme={null}
  // Typical usage: redirect in a button click handler
  const handleManageBilling = () => {
    // The endpoint will redirect to Stripe Customer Portal
    window.location.href = "/api/v1/operations/payment/customer-portal";
  };
  ```

  ```jsx React theme={null}
  // Usage in a React component
  function BillingButton() {
    return (
      <a href="/api/v1/operations/payment/customer-portal">Manage Billing</a>
    );
  }
  ```
</RequestExample>

<ResponseExample>
  ```http Success Response theme={null}
  HTTP/1.1 302 Found
  Location: https://billing.stripe.com/p/session/test_abc123...
  ```

  ```json Error Response (Unauthorized) theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Authentication required"
    }
  }
  ```

  ```json Error Response (No Organization) theme={null}
  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Organization ID is required"
    }
  }
  ```

  ```json Error Response (No Stripe Customer) theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "message": "Stripe customer for organization org_abc123 not found"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Status Code | Error Code         | Description                                         |
| ----------- | ------------------ | --------------------------------------------------- |
| `401`       | `UNAUTHORIZED`     | User is not authenticated                           |
| `400`       | `VALIDATION_ERROR` | User is not associated with an organization         |
| `404`       | `NOT_FOUND`        | Organization does not have a Stripe customer record |
| `500`       | `INTERNAL_ERROR`   | Server error while creating portal session          |

## Prerequisites

Before a user can access the Customer Portal, the organization must:

1. **Have a Stripe customer record** - Created automatically when the organization first subscribes or purchases credits
2. **Be properly authenticated** - User must be logged in via Clerk
3. **Be associated with an organization** - User must be a member of an organization

## Notes

* This endpoint performs a redirect and does not return JSON on success
* The Stripe Customer Portal session is valid for a limited time
* All billing operations in the portal are handled securely by Stripe
* Changes made in the portal (subscription updates, cancellations) are synchronized back to the application via Stripe webhooks