Skip to main content
POST
/
api
/
v1
/
payments
/
stripe
/
customer-portal
Create Customer Portal Session
curl --request POST \
  --url https://api.devkit4ai.com/api/v1/payments/stripe/customer-portal \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "return_url": "<string>"
}
'
{
  "portal_url": "<string>"
}
Create a Stripe Customer Portal session that lets users manage their subscriptions, payment methods, and billing details directly in Stripe’s hosted interface.

Authentication

This endpoint requires end user authentication via HTTP Bearer Token with project scope.

Query Parameters

test_mode
boolean
default:"true"
Use test mode credentials. Set to false for production.

Request Body

return_url
string
required
URL to redirect user after they exit the portal

Response

portal_url
string
URL to redirect user to the Stripe Customer Portal

Example Request

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

{
  "portal_url": "https://billing.stripe.com/p/session/test_YWNjdF8xQUJDMTIzZG"
}

Portal Flow

Portal Capabilities

The Customer Portal allows users to:
CapabilityDescription
View InvoicesSee and download past invoices
Update Payment MethodAdd or change credit/debit cards
Cancel SubscriptionEnd their subscription
Change PlanUpgrade or downgrade (if configured)
Update Billing InfoChange billing email and address
Configure portal features in Stripe Dashboard > Settings > Customer Portal.

Integration Example

// 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

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.

Error Responses

StatusDescription
401Unauthorized - Invalid or missing authentication
404No Stripe customer found for user
404Project not found or Stripe not configured
422Validation error - Invalid return_url

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

test_mode
boolean
default:true

Use test mode

Body

application/json

Request to create a customer portal session.

return_url
string
required
Minimum string length: 1

Response

Successful Response

Customer portal session response.

portal_url
string
required