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

# Create Customer Portal Session

> Create a Stripe Customer Portal session for users to manage billing

Create a Stripe Customer Portal session that lets users manage their subscriptions, payment methods, and billing details directly in Stripe's hosted interface.

## Authentication

<Note>
  This endpoint requires end user authentication via HTTP Bearer Token with project scope.
</Note>

## Query Parameters

<ParamField query="test_mode" type="boolean" default="true">
  Use test mode credentials. Set to `false` for production.
</ParamField>

## Request Body

<ParamField body="return_url" type="string" required>
  URL to redirect user after they exit the portal
</ParamField>

## Response

<ResponseField name="portal_url" type="string">
  URL to redirect user to the Stripe Customer Portal
</ResponseField>

## Example Request

```bash theme={null}
curl -X POST "https://api.devkit4ai.com/api/v1/payments/stripe/customer-portal?test_mode=true" \
  -H "Authorization: Bearer {end_user_jwt}" \
  -H "Content-Type: application/json" \
  -d '{
    "return_url": "https://myapp.com/account/billing"
  }'
```

## Example Response

```json theme={null}
{
  "portal_url": "https://billing.stripe.com/p/session/test_YWNjdF8xQUJDMTIzZG"
}
```

## Portal Flow

```mermaid theme={null}
sequenceDiagram
    participant U as User
    participant App as Your App
    participant API as Cloud API
    participant Portal as Stripe Portal

    U->>App: Click "Manage Billing"
    App->>API: POST /customer-portal
    API-->>App: portal_url
    App->>U: Redirect to Stripe Portal
    U->>Portal: Update payment/subscription
    Portal-->>U: Redirect to return_url
```

## Portal Capabilities

The Customer Portal allows users to:

| Capability                | Description                          |
| ------------------------- | ------------------------------------ |
| **View Invoices**         | See and download past invoices       |
| **Update Payment Method** | Add or change credit/debit cards     |
| **Cancel Subscription**   | End their subscription               |
| **Change Plan**           | Upgrade or downgrade (if configured) |
| **Update Billing Info**   | Change billing email and address     |

<Tip>
  Configure portal features in **Stripe Dashboard > Settings > Customer Portal**.
</Tip>

## Integration Example

```typescript theme={null}
// Manage billing button component
function ManageBillingButton() {
  const [loading, setLoading] = useState(false);

  const handleManageBilling = async () => {
    setLoading(true);
    try {
      const response = await fetch('/api/customer-portal', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          return_url: window.location.href
        })
      });
      
      const { portal_url } = await response.json();
      window.location.href = portal_url;
    } catch (error) {
      console.error('Failed to open portal:', error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <button onClick={handleManageBilling} disabled={loading}>
      {loading ? 'Loading...' : 'Manage Billing'}
    </button>
  );
}
```

## Portal Configuration

Configure allowed actions in Stripe Dashboard:

(((REPLACE\_THIS\_WITH\_IMAGE: stripe-customer-portal-settings.png: Stripe Dashboard Customer Portal configuration page showing subscription and invoice settings)))

## Prerequisites

<Warning>
  The user must have an existing Stripe Customer ID from a previous checkout. If the user has never subscribed, this endpoint will return an error.
</Warning>

## Error Responses

| Status | Description                                      |
| ------ | ------------------------------------------------ |
| `401`  | Unauthorized - Invalid or missing authentication |
| `404`  | No Stripe customer found for user                |
| `404`  | Project not found or Stripe not configured       |
| `422`  | Validation error - Invalid return\_url           |

## Related Pages

<CardGroup cols={2}>
  <Card title="Get My Subscription" icon="user" href="/cloud-api/payments/stripe/get-my-subscription">
    Check subscription status
  </Card>

  <Card title="Cancel Subscription" icon="xmark" href="/cloud-api/payments/stripe/cancel-subscription">
    Cancel programmatically
  </Card>

  <Card title="Update Subscription" icon="arrows-rotate" href="/cloud-api/payments/stripe/update-subscription">
    Change plans via API
  </Card>
</CardGroup>


## OpenAPI

````yaml POST /api/v1/payments/stripe/customer-portal
openapi: 3.1.0
info:
  title: Dev Kit for AI API
  description: 'API for Dev Kit for AI: Developer Toolkit for AI-Powered Web Applications'
  version: 1.6.1
servers:
  - url: https://api.devkit4ai.com
    description: Dev Kit for AI Production Server
  - url: https://api.vibecoding.ad
    description: Vibe Coding Production Server
security: []
paths:
  /api/v1/payments/stripe/customer-portal:
    post:
      tags:
        - Stripe Subscriptions
      summary: Create Customer Portal Session
      description: >-
        Create a Stripe Customer Portal session for the user to manage their
        subscription, payment methods, and billing details.
      operationId: create_customer_portal_api_v1_payments_stripe_customer_portal_post
      parameters:
        - name: test_mode
          in: query
          required: false
          schema:
            type: boolean
            description: Use test mode
            default: true
            title: Test Mode
          description: Use test mode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerPortalRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerPortalResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    CustomerPortalRequest:
      properties:
        return_url:
          type: string
          minLength: 1
          title: Return Url
      type: object
      required:
        - return_url
      title: CustomerPortalRequest
      description: Request to create a customer portal session.
    CustomerPortalResponse:
      properties:
        portal_url:
          type: string
          title: Portal Url
      type: object
      required:
        - portal_url
      title: CustomerPortalResponse
      description: Customer portal session response.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````