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
Use test mode credentials. Set to false for production.
Request Body
URL to redirect user after they exit the portal
Response
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:
| 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 |
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
| 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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Request to create a customer portal session.
Customer portal session response.