Self-Service Actions

The self-service surface

Once a customer has a portal session (magic link), these /portal/api/* actions are available — all authenticated by the portal_session cookie. This is the real, shipped surface; which of these you expose is configured in the dashboard under Settings → Portal.

View & pay invoices

# List the customer's invoices
curl https://billing.example.com/portal/api/invoices -b cookies.txt

# Download one as a PDF
curl https://billing.example.com/portal/api/invoices/{invoice_id}/pdf \
  -b cookies.txt -o invoice.pdf

To pay, send the customer to the hosted checkout for the open invoice (/checkout/{invoice_id}) — see Payments.

Update the card on file (Stripe)

Card updates use a Stripe SetupIntent so the card never touches your servers. Start it, collect the card with Stripe Elements using the returned client_secret, then confirm:

# 1. Start — returns a client_secret for Stripe Elements
curl -X POST https://billing.example.com/portal/api/payment-method/setup-intent \
  -b cookies.txt

# 2. (browser) confirm the SetupIntent with Stripe.js using client_secret

# 3. Finalize — saves the card metadata on the customer
curl -X POST https://billing.example.com/portal/api/payment-method/confirm \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{ "setup_intent_id": "seti_..." }'

The confirm call returns status: "saved" with the new card’s brand and last four, or status: "processing" for methods that settle asynchronously. For US customers, the payment-method page also offers a bank account (ACH): start with POST /portal/api/payment-method/bank-setup-intent, run Stripe Financial Connections in the browser for instant verification, then finalize with the same confirm call — the saved method shows the bank name and last four. See Set up ACH bank debits.

If the deployment isn’t configured for self-serve card updates, these endpoints return a clear “not available on this deployment” error rather than failing silently.

Re-authorize a UPI AutoPay mandate

For Indian customers on UPI AutoPay, the portal issues a fresh mandate and returns a hosted authorization URL to redirect to:

curl -X POST https://billing.example.com/portal/api/payment-method/mandate \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{ "vpa": "customer@upi" }'    # vpa optional — Razorpay collects it if omitted

{ "data": { "auth_url": "https://razorpay.com/..." } }

Redirect the customer to auth_url to approve the mandate in their UPI app.

Raise a dispute

A customer can query or dispute one of their own invoices:

curl -X POST https://billing.example.com/portal/api/invoices/{invoice_id}/dispute \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{ "reason": "I was charged twice for this invoice." }'

Open disputes are listed at GET /portal/api/disputes.

Redeem a gift code

curl -X POST https://billing.example.com/portal/api/redeem \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{ "code": "GIFT-XXXX" }'

See Gifts for how codes are purchased.

Cancellation

Subscription cancellation runs through the dedicated cancellation flow — surveys, retention offers, and confirmation — rather than a single portal endpoint.

Log out

curl -X POST https://billing.example.com/portal/api/logout -b cookies.txt

Get Started

Migrate to Recurso

Core Concepts

Usage & Monetization

Money & Books

Tax & Compliance

Recover & Retain

Customer Portal

Platform & Integrations

Deploy & Operate

Reference

The self-service surface

View & pay invoices

Update the card on file (Stripe)

Re-authorize a UPI AutoPay mandate

Raise a dispute

Redeem a gift code

Cancellation

Log out

​The self-service surface

​View & pay invoices

​Update the card on file (Stripe)

​Re-authorize a UPI AutoPay mandate

​Raise a dispute

​Redeem a gift code

​Cancellation

​Log out

The self-service surface

View & pay invoices

Update the card on file (Stripe)

Re-authorize a UPI AutoPay mandate

Raise a dispute

Redeem a gift code

Cancellation

Log out