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 401Unauthorized - Invalid or missing authentication 404No Stripe customer found for user 404Project not found or Stripe not configured 422Validation error - Invalid return_url
Related Pages
Get My Subscription Check subscription status
Cancel Subscription Cancel programmatically
Update Subscription Change plans via API
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.