Billing portal

Create a Stripe Customer Portal session for managing subscriptions and payment methods.

POST /api/payments/billing-portal

Billing portal

cURL

curl --request POST \
  --url https://api.example.com/api/payments/billing-portal \
  --header 'Authorization: <authorization>'

200

{
  "message": "<string>",
  "data": {
    "url": "<string>"
  }
}

This endpoint requires a valid Bearer token and an existing Stripe customer account. Users on the free plan who have never subscribed will receive a 400 error.

Creates a Stripe Customer Portal session and returns a redirect URL. The portal is a Stripe-hosted page where users can:

• Update or replace their payment method
• View past invoices and download receipts
• Cancel or reactivate a scheduled cancellation
• Review billing history

After the user is done, Stripe redirects them back to the /settings page in the Hayon frontend.

Authentication

Authorization · string · required

Bearer token. Format: Bearer <token>.

Prerequisites

The authenticated user must have a stripeCustomerId on file. This is set automatically when the user first completes a checkout session. Calling this endpoint without a prior subscription returns:

{
  "message": "No billing account found. Please subscribe first."
}

Response

On success the server returns 200 OK with a JSON body containing a single-use Stripe Customer Portal URL.

message · string

Human-readable status message.

data · object

Hide properties

url · string · required

The Stripe-hosted billing portal URL. Redirect the user to this address. The URL is short-lived and single-use.

Behavior

• Changes made in the portal (e.g., toggling a cancellation) are communicated back to the server via Stripe webhooks. The customer.subscription.updated event keeps the database in sync.
• The portal session return URL is configured to send the user back to /settings after they exit.

The returned url is single-use. If the user’s session expires, call this endpoint again to generate a fresh URL.

Example

cURL

curl --request POST \
  --url https://api.hayon.app/api/payments/billing-portal \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Success response

{
  "message": "Billing portal session created",
  "data": {
    "url": "https://billing.stripe.com/p/session/test_YWNjdF8xTzBTVGFCdUhyZ3JhTkJ4LF9RZlQ0eUhwUkdMRzFmRFR5d2lQUFFZVG9jbloxSnlm0100KgiqMBKb"
  }
}

Error responses

400

{
  "message": "No billing account found. Please subscribe first."
}

401

{
  "message": "Unauthorized"
}

500

{
  "message": "Failed to open billing portal"
}

Portal flow

1. Request a portal URL

   Call POST /api/payments/billing-portal with the user’s Bearer token.

2. Redirect the user

   Redirect the browser to the url returned in the response body.

3. User manages their subscription

   The Stripe-hosted portal lets the user update payment methods, view invoices, and manage cancellation.

4. User returns to settings

   After exiting the portal, Stripe redirects the user to /settings. Any subscription changes are synced via webhook.