Customer Portal Integration

Let customers manage their billing and subscriptions

The Customer Portal gives your customers a self-service interface to view invoices, update payment methods, and manage subscriptions. Send customers a link to access their billing information.

---

How It Works

---

Sending Portal Access

Via Dashboard

Send a portal link directly to a customer:

1. Navigate to Customers → [Customer Name]
2. Click Send Portal Link or Send Billing Email
3. Customer receives an email with a secure link
4. The link is short-lived and single-use

Via Your Application

Create a portal session with POST /customer-portal-sessions and redirect the customer to the url it returns.

See Customer Portal for the request shape and the per-section settings.

---

What Customers Can Do

View Invoices

Customers can see all their invoices:

• Current and past invoices
• Invoice status (paid, pending, overdue)
• Download invoice PDFs
• View line item details

Update Payment Method

Customers can manage their payment methods:

• Add new credit card
• Update existing card
• Set default payment method
• Add bank account (if enabled)

View Subscription

Customers can see their subscription details:

• Current plan and pricing
• Billing cycle dates
• Next invoice date
• Contract terms

Self-Service Changes

If enabled, customers can:

• Upgrade to a higher plan
• Downgrade to a lower plan
• Add or remove seats
• Cancel subscription

---

Portal Configuration

Settings → Customer Portal

Configure what customers can do:

Feature	Description
Plan overview	Show the subscription, next charge and pricing breakdown
Self-serve changes	Let the customer change plan without contacting you
Cancel subscription	Let the customer cancel
Invoice list	Show invoice history with PDF downloads
Billing details	Show company details and payment methods
Edit account details	Let the customer edit their own billing details
Edit payment method	Let the customer add or change a payment method
Edit autopay	Let the customer turn autopay on or off

These are your organization’s defaults. A portal session can override any of them for a single customer.

Enabling Self-Service

1. Navigate to Settings → Customer Portal
2. Enable self-serve plan changes and, if you want it, self-cancellation
3. Save settings

To allow it for some customers but not others, leave the defaults restrictive and pass plan_overview_settings.allow_self_serve_change on the sessions where it should be available.

---

Branding

Customize the portal appearance:

1. Navigate to Settings → Branding
2. Upload your logo
3. Set primary colors
4. Configure footer text
5. Preview the portal

The portal will match your brand colors and display your logo.

---

Portal Sessions

Session Expiration

Each session carries an expires_at and is single-use. Create a session when the customer clicks through to billing rather than emailing a link you generated earlier.

Security

• Each link is unique and single-use
• Sessions are tied to a specific customer
• No login required, so the link is the credential: treat it as a secret

---

Webhooks

Receive notifications when customers take action:

Event	When Sent
subscription.updated	The subscription changed
subscription.cancelation_scheduled	The customer scheduled a cancellation
subscription.canceled	The cancellation took effect
payment.created	A payment was started
payment.updated	A payment changed status

Configure webhooks in Settings → Webhooks. See Webhooks for the full event list and payloads.

---

Common Use Cases

”Manage Billing” Button

Add a button in your app that takes customers to the portal:

1. Create a /billing route in your application
2. When it is accessed, create a portal session and redirect to the session url
3. Because sessions are single-use, create a fresh one on every visit

Payment Method Only

To narrow the portal to payment details, hide the other sections on the session:

• plan_overview_settings.show_section: false
• invoice_list_settings.show_section: false
• billing_details_settings.allow_payment_method_edit: true

Invoice Access

To give customers invoices and nothing else, show only the invoice list:

• invoice_list_settings.show_section: true
• plan_overview_settings.show_section: false

---

Troubleshooting

Portal Link Not Working

1. Check the session’s expires_at — it may have lapsed
2. Check whether the link has already been used; sessions are single-use
3. Verify the customer exists, then create a new session

Customer Can’t See Invoices

1. Verify the customer has invoices
2. Check that invoice_list_settings.show_section is not set to false on the session, and that the section is enabled in your organization defaults

Self-Service Changes Not Available

1. Check that self-service is enabled in Settings → Customer Portal
2. Verify the plans allow self-service changes
3. Ensure the customer’s current plan permits changes

---

Best Practices

Easy Access

Add a clear “Manage Billing” link in your app navigation.

Brand Consistently

Configure branding so the portal matches your app.

Limit Self-Service

Control which changes customers can make on their own.

Handle Webhooks

Listen for portal events to keep your app in sync.

---

Next Steps

Customer Portal

Full portal configuration and API reference.

Hosted Checkout

Set up hosted checkout pages.