> For the complete documentation index, see [llms.txt](https://docs.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.younium.com/sales-and-product-led-growth/self-service.md). # Self Service ## Overview Younium Self Service is a customer-facing platform that lets SaaS providers give their end customers secure access to invoices, subscriptions, and account information. It operates as a thin layer on top of the Younium API: billing data, product names, prices, and subscription state always come from Younium as the system of record. Self Service stores only configuration flags, user directories, and audit logs. The platform offers three delivery modes. The **Self Service Hub** is the operator cockpit for configuring portals, branding, feature toggles, and API credentials. The **Hosted Customer Portal** is a fully branded, standalone portal with passwordless login — no custom development required. **Embedded Components** are JavaScript widgets that render self-service UI inside a tenant's own website, authenticated via short-lived tokens issued by the tenant's backend. Self Service connects naturally to product-led growth workflows alongside [CPQ](/sales-and-product-led-growth/cpq.md) and [Paywall](/sales-and-product-led-growth/paywall.md). CRM integrations such as [HubSpot](/crm-integrations/hubspot.md) and [Salesforce](/crm-integrations/salesforce.md) complement Self Service when customer data originates in a CRM before subscription management in Younium. | Environment | Hub | Portal | | ----------- | --------------------------------- | ------------------------------------------- | | Production | `https://selfservice.younium.com` | `https://customerportal.younium.com/{slug}` | | Sandbox | `https://selfservice.younium.net` | `https://customerportal.younium.net/{slug}` | *** ## Core Concepts ### Self Service Hub The Hub is the authoritative configuration layer for Self Service. Operators with the **Edit SelfService** permission configure portal branding, feature toggles, subscription and addon rules, customer portal users, email templates, and API credentials for embedded components. The Hub connects to Younium using API credentials stored during setup. ### Hosted Customer Portal The portal is a white-label customer experience served at a tenant-specific URL slug. Customers authenticate via email magic link (passwordless). Once authenticated, they access invoices, subscriptions, and account information according to the feature toggles configured in the Hub. Portal routes include dashboard, invoices, account, subscriptions, and user management (customer admin role only). ### Embedded Components (SDK) The JavaScript SDK renders self-service UI inside any web page. Three components are available: | Component | Capability | | ------------------- | --------------------------------------------------------------------- | | `invoice-list` | Search, pagination, PDF download | | `account-info` | View and edit invoice email and billing address | | `subscription-list` | View subscriptions, edit quantities, manage addons and tiered pricing | The SDK is loaded from Younium's content delivery network, with the version in the path: | Environment | Script | | ----------- | ------------------------------------------------------------------------ | | Production | `https://cdn.younium.com/selfservice-sdk/v3.0.0/younium-embedded-sdk.js` | | Sandbox | `https://cdn.younium.net/selfservice-sdk/v3.0.0/younium-embedded-sdk.js` | The Hub's Get Started page shows the exact script tag for the environment you are in, and the Hub serves the same versions from its own address. A minified build is available at the same path with `.min.js`. The tenant's backend obtains a short-lived access token using API credentials; the browser never sees API secrets. ### Self Service API The API is the secure gateway between the Portal, SDK, and Younium. It enforces tenant and customer isolation, scope checks, customer identifier mapping, and activity logging. All product names, prices, and subscription data are fetched live from Younium — Self Service stores only Younium entity IDs and configuration flags. *** ## Behaviour and Rules ### Authentication **Hub operators** sign in with their Younium credentials and select a legal entity. Access requires the **Edit SelfService** permission in Younium. **Portal customers** authenticate via email magic link. If an email maps to multiple customer accounts, the portal presents an account selection step. Magic links expire after 15 minutes. Portal sessions last 24 hours by default. A new login invalidates any previous active session for the same customer. Unknown email addresses receive no indication of whether the address exists (anti-enumeration). **Embedded components** authenticate via a short-lived access token issued by the tenant's backend. A token lasts an hour unless the backend asks for a different lifetime, and the SDK can fetch a fresh one without the customer noticing. ### Tenant isolation All data is scoped by tenant and legal entity. Every API request validates the customer's identity and authorised scope. ### Scope enforcement (embedded tokens) | Scope | Allows | | --------------------- | --------------------------------------------------- | | `read:invoices` | Invoice list, detail, PDF | | `read:account` | Account profile | | `write:account` | Update invoice email and billing address | | `read:subscriptions` | Subscription list | | `write:subscriptions` | Quantity changes, addon requests, price calculation | Portal sessions bypass scope checks. Embedded tokens enforce scopes on every request. ### Portal features Feature toggles control what customers see in the hosted portal: | Feature | What it allows | | --------------------------- | ----------------------------------------------------------- | | **Invoice Management** | View and download invoices | | **Subscription Management** | View subscription details and line items | | **Account Management** | View and edit the invoice email address and billing address | There are three toggles and no more. User management is controlled by the customer's own role — User or Admin — not by a feature toggle. ### Invoice and payment behaviour The portal displays **Pay Now** only when the invoice is **Posted** and carries an online payment link from Younium. Clicking the link opens the payment provider URL in a new tab. Self Service does not process payments itself — online payment must be configured in Younium [Payments](/platform/payments.md). Only **Posted** and **Settled** invoices reach the customer. Drafts and cancelled invoices are never listed, and a posted invoice that has been part-paid stays Posted with its outstanding balance shown — Younium has no separate part-paid status. ### Subscription changes What a customer may change is decided in the Hub under **Subscriptions**, on the Subscriptions Configuration page. The rules there are merged with live Younium subscription data on every request: 1. The customer calculates the price impact via the API. 2. The customer submits a change request. 3. The API validates the request against the configured rules: the product is enabled, the charge allows a change in that direction, the new quantity is within its bounds, and an add-on being added is an enabled, addable product. 4. On success, the change is forwarded to the Younium subscription change API and recorded in the activity log. A product is added to the page before anything about it can be configured; products that have not been added are invisible to customers. **Per product:** | Setting | Effect | | ----------- | ----------------------------------------------------------------------- | | **Addable** | Customers can add this product to an existing subscription as an add-on | **Per charge plan**, where a product has more than one: a switch that includes or excludes the whole plan. **Per charge:** | Setting | Effect | | ----------------------------------- | ------------------------------------------------------------------------ | | Enabled | The charge is visible to the customer | | **Allow Increase** | The customer can raise the quantity — an upsell they can make themselves | | **Allow Decrease** | The customer can lower the quantity | | **Min Quantity** / **Max Quantity** | The bounds a customer must stay within, under Advanced | Quantity settings appear only on charges that are priced by quantity — not on usage or measured charges. The edit button reaches the customer only when the charge is enabled and at least one of increase or decrease is allowed, and a change outside the bounds is refused with the limit named. Add-ons follow the same two settings rather than a set of their own: a product is offered as an add-on when it is enabled and marked **Addable**. ### Data merge pattern Self Service never stores product names, prices, or charge types locally. For every request, live Younium API data is merged with local configuration flags (enabled, editable, min/max) keyed by Younium entity ID. The merged result drives the customer-facing UI. *** ## Configuration and Settings ### Hub configuration areas | Area | What is configured | | ------------------- | -------------------------------------------------------------------------------- | | **Younium API** | Client ID and secret, with a connection test | | **Configuration** | Portal on or off, URL slug, title, branding, feature toggles | | **Subscriptions** | Which products, charge plans and charges customers see, and what they may change | | **Users** | Portal user invites, roles (User or Admin), bulk import from a CSV file | | **Email Templates** | Welcome and magic link subject and HTML, with merge tags | | **API Credentials** | Embedded component keys, allowed origins, scopes | | **Components** | Integration guidance and code samples for the embedded components | | **Playground** | Renders a component live against your own credentials | | **Activity Logs** | Audit trail, filterable and exportable to CSV | ### Portal branding The Configuration page carries the portal title, the URL slug, a **Primary Color**, a logo URL, a favicon URL, and optional custom CSS for anything the standard settings do not cover. The slug accepts lowercase letters, numbers and hyphens, and the page shows the finished portal address as you type it. Branding applies to the hosted portal only; embedded components inherit styling from the host page unless the SDK is initialised with a theme of its own. ### API credentials (embedded) Each credential record includes an API key and secret (secret shown once at creation), allowed origins for CORS, and assigned scopes. Credentials are hashed at rest. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.younium.com/sales-and-product-led-growth/self-service.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.