Customer Portal (hosted billing)
The customer portal is Stream’s hosted web app (billing.streampay.sa) where your consumers sign in and manage their relationship with you, within limits you configure in Stream: subscriptions (plan changes, quantity adjustment, and add‑ons allowed by your catalog), invoices, saved cards, profile and language, and payment flows that use Stream checkout.
Prerequisites
- Consumer in Stream — The person must exist as an organization consumer (Stream’s customer record). Create one with the Create Consumer API (or your existing consumer flow) and use the returned
idasorganization_consumer_idwhen creating a portal session. - Merchant API credentials — Your backend calls Stream with
x-api-key; see Authentication.
Send a consumer to the portal
Call from your server only (never expose your API secret or full key pair in a browser or app) this endpoint to get the one-time use token to open the customer portal for a specific consumer ID.
Body (minimum)
| Field | Required | Description |
|---|---|---|
organization_consumer_id | Yes | The consumer’s UUID in Stream (id from Create Consumer or list consumers). |
Response
On success (HTTP 201) the JSON includes a url. Return that url to your frontend and open it so the consumer lands on the billing portal.
You can optionally include return_url (query hint for “back to merchant”; Stream does not auto-redirect), subscription_id to open a specific subscription for that consumer, or other optional fields supported by the API—see the reference for the full request schema.
What subscription self-service means
When your settings allow it, a customer can change an active subscription from the portal. Stream validates every change against your catalog and portal rules. Below is what each kind of change means in plain terms.
Switching plans
Plan switching is when the customer moves from one base subscription product to another member of the same product switch group you defined in Stream. Only products you placed in that group can replace one another; the portal does not allow arbitrary jumps across unrelated products. Plans with different recurring cycles (e.g MONTHLY and YEARLY) can be added in the same switch group.
Typical shape of a switch: one billed base line is removed and another base line (the new plan) replaces it within the rules of that group. Whether this appears as an immediate change or is scheduled depends on billing setup and proration logic (see Proration and timing).
Subscriptions with coupon locked at subscription level usually cannot be edited from the portal. Coupons on lines you keep can persist; lines you remove lose their coupons.
Add-ons
Add-ons are separate catalog products attached to an active subscription—not the main plan by itself. Each add-on is only available when the subscription’s base catalog products make it eligible. You declare that relationship in Stream (which bases may carry which add-ons).
Customers can subscribe or drop add-ons in the portal only when you enable add / remove add-ons for Customer Portal and the add-on mapping allows it.
When creating an add-on, you get to choose a list of recurring products for which the add-on is eligible. In case a subscription has multiple recurring products and the recurring products have different eligible add-ons, the customer will be able to add all of these add-ons.
Changing quantity
Quantity changes behave differently depending on whether the line is part of your switch group (often “seat-like” bases) versus an add-on:
| Kind of line | What “quantity” means | How you control it |
|---|---|---|
| Products in switch groups | How many seats or units apply to that base plan row | Toggle switch-group quantity change in Customer Portal settings. When enabled, you can constrain minimum and maximum quantities; when disabled, customers cannot freely change those quantities in the portal. |
| Add-on lines | How many units of that add-on are on the subscription | Toggle add-on quantity change. When quantity change is off for new add-ons, new add-ons are typically limited to quantity one until you widen the rule. |
The portal compares changes to allowed quantities only; anything outside configured bounds is rejected.
Proration and timing
Proration is how billing adjusts when the subscription mid-cycle gains or loses value: Stream compares what was prepaid or owed for the current period against what the revised subscription implies, and settles the difference—often creating an invoice line or prompting payment before the next renewal. Proration does not include the current day in the new pricing. For example, if a monthly subscription (30 days) was created today and then in the same day an add-on gets added immediately through proration, the proration excludes the current day from the new bill (i.e. the user pays 29 / 30 days worth of add-on instead of 30/30.)
Roughly:
-
Adding add-ons, raising quantity, or some plan upgrades commonly produce immediate charges (or payment steps) when money is owed, because billing value rises right away relative to what was invoiced.
-
Removing add-ons, lowering quantity, or changing plans in directions that reduce or reshape future billing often take effect according to billing rules. For example at period end or as a scheduled change rather than forcing an instant upfront payment in every case.
-
When a change crosses into a different billing rhythm than the subscription’s targets, moves are often scheduled for a future boundary rather than squeezed into an immediate payment-only flow inside the portal.
From the customer’s perspective, the portal either confirms the change outright, shows a payment or card step when an adjustment is due now, or explains that the change applies later in the billing period—depending on the scenario above. Until any required payment clears, billing may remain on the previous shape until reconciliation finishes.
Exact math and timing depend on your products’ recurrence and Stream’s reconciliation; you do not re-implement proration in your integration.
Configure Customer Portal, branding, and catalog
Open the Stream dashboard, then Settings → Customer Portal. There you tune both permissions customers get and branding of billing.streampay.sa.
Portal permissions (toggles)
These settings mirror what you enable in Customer Portal Settings in the UI—they define what edits the hosted app even offers:
| Setting | Meaning for your customers |
|---|---|
| Product switch | Can move between products you grouped in product switch groups (plan changes within your allowed set). |
| Add / remove add-ons | Can attach or remove add-ons you exposed through add-on eligibility. |
| Switch-group quantity change | Can change quantity on base lines that belong to switch groups, within optional min / max when enabled. |
| Add-on quantity change | Can change quantity on add-on lines, within optional min / max when enabled. |
| Subscription cancellation | Customer-led cancellation inside portal flows is on or off. |
Branding
On the same Customer Portal settings area, you can personalize the hosted experience:
- Primary color and secondary color — Applied across the portal UI so it feels closer to your brand.
- Favicon — Shown in the browser tab when customers use the billing site.
Uploads and color pickers persist with your organization so every session link inherits the same look.
Catalog prerequisites (beyond the toggles)
Customer Portal switches and add-ons only work if the catalog is set up to match:
| Goal | What to set up in Stream |
|---|---|
| Allowed plan moves | Create product switch groups and assign which products belong to each group. Only members of the same group can replace one another. |
| Which add-ons exist for which bases | Maintain add-on mappings: for each add-on product, declare which base products make it eligible. |
Until those mappings exist, toggles alone will not expose meaningful switches or add-ons in the portal.
Summary
| Role | Responsibility |
|---|---|
| Your backend | POST /api/v2/consumer_portal/sessions with organization_consumer_id, then return url to the client. |
| Your frontend | Open url; do not use the merchant API key in the browser. |
| billing.streampay.sa | Hosts the customer portal once the consumer opens **url. |
For API key setup and authentication, see Authentication.