# Hyperline CLI Source: https://docs.hyperline.co/api-reference/docs/ai/cli Use the Hyperline CLI — an agent-first command-line tool — to query customers, subscriptions, invoices, and events directly from your terminal. The [Hyperline CLI](https://www.npmjs.com/package/@hyperline/cli) lets you manage your billing operations directly from the terminal. It's designed to be **agent-first** — optimized for AI agents like Claude Code, Cursor, Windsurf, and any tool that can run shell commands. ## Why a CLI for AI agents? AI agents work with tools to accomplish tasks. Today, most agents use MCP (Model Context Protocol) to connect to external services. While MCP works well, it has limitations when used at scale: * **Context bloat** — MCP servers expose dozens of tools, each with full schemas that consume valuable context window space. * **Slower on complex tasks** — For multi-step workflows, agents using MCP need to discover tools, read schemas, and format structured requests for each operation. On complex questions, MCP agents can loop for minutes trying to find the right tool combination. CLIs solve these problems: * **Token-efficient** — Short commands like `hyperline customers list` are natural for a text-predicting model to write and require minimal context to understand. * **No tool discovery overhead** — Agents don't need to load a catalog of tools or read JSON schemas. They just run commands and read the output. * **Composable** — CLI output can be piped, filtered with `jq`, or chained with other commands — patterns that agents handle natively. ## Installation ```bash theme={null} npm install -g @hyperline/cli ``` Verify the installation: ```bash theme={null} hyperline --version ``` ## Authentication ### Browser login The simplest way to authenticate — opens your browser to securely log in with your Hyperline account: ```bash theme={null} hyperline login ``` Credentials are stored locally in `~/.hyperline/`. To log out: ```bash theme={null} hyperline logout ``` ### API key For server environments, CI/CD pipelines, or AI agents running without a browser: ```bash theme={null} # Via environment variable export HYPERLINE_API_KEY=sk_test_... # Or inline hyperline customers list --api-key sk_test_... ``` API keys can be generated from your account [Settings](https://app.hyperline.co/app/settings/api). Keep your API key secret. Do not commit it to version control — use environment variables or a secrets manager instead. For sandbox environments, set the base URL via environment variable or flag: ```bash theme={null} export HYPERLINE_API_URL=https://api.sandbox.hyperline.co # Or per-command hyperline customers list --base-url https://api.sandbox.hyperline.co ``` ## Company selection If you have access to multiple companies, the CLI uses the last used company by default. To switch to a specific company: ```bash theme={null} hyperline company select ``` ## Usage The CLI follows a consistent `hyperline ` pattern: ```bash theme={null} # List customers hyperline customers list # Get a specific invoice hyperline invoices get --id inv_xxxxx # Create a new customer hyperline customers create --name "Acme Inc" --currency USD ``` ### Available resources | Resource | Description | | -------------------- | ----------------------------------------------------------- | | `customers` | Create, update, list, and manage your customer base | | `subscriptions` | Handle subscription lifecycle, cancellations, and templates | | `invoices` | Create, list, and manage invoices and transactions | | `products` | Define and update your product catalog | | `quotes` | Generate and manage quotes | | `wallets` | Prepaid wallet management and top-ups | | `coupons` | Create discount coupons and promotion codes | | `webhooks` | Configure webhook endpoints | | `payments` | Track and manage payments | | `analytics` | Access billing metrics | | `exports` | Export your billing data | | `custom-properties` | Extend resources with custom fields | | `taxes` | View tax rates and configurations | | `invoicing-entities` | Manage your billing entities | Use `--help` on any command to see available actions and options: ```bash theme={null} hyperline customers --help hyperline invoices list --help ``` ### Output formats By default, the CLI outputs human-readable text. Use `--output json` for structured output: ```bash theme={null} # Human-readable output hyperline customers list # JSON output for scripting hyperline customers list --output json # Pipe to other tools hyperline customers list --output json | jq '.[].name' ``` ### Global options | Option | Description | | ------------------- | -------------------------------------------- | | `--api-key ` | API key (overrides `HYPERLINE_API_KEY`) | | `--base-url ` | API base URL (overrides `HYPERLINE_API_URL`) | | `--output ` | `json` or `text` (default: `text`) | | `--help` | Show help | | `--version` | Show version | ## Setting up for AI agents ### Claude Code Add the Hyperline CLI to your project's `CLAUDE.md` so Claude knows it's available: ```markdown theme={null} ## Tools Hyperline CLI is available for billing operations. Authenticate with: `export HYPERLINE_API_KEY=sk_...` Usage: `hyperline [options]` Use `--output json` when you need to process the data. ``` ### Cursor / Windsurf Add instructions to your project rules (`.cursor/rules/` or `.windsurfrules`) so the agent knows to use the CLI: ```markdown theme={null} ## Billing Use the Hyperline CLI for any billing-related tasks. Run `hyperline ` commands in the terminal. Use `--output json | jq` for filtering and processing data. ``` ### Any agent with shell access Any AI agent that can execute shell commands can use the Hyperline CLI. Set the `HYPERLINE_API_KEY` environment variable in the agent's environment, and the CLI is ready to use — no additional configuration or tool registration needed. ## CLI vs MCP — which should I use? | | CLI | MCP | | -------------------- | ------------------------------------------------------- | ---------------------------------------------------------- | | **Best for** | AI agents with shell access, scripting, automation | AI assistants without terminal access (Claude.ai, ChatGPT) | | **Setup** | `npm install -g @hyperline/cli` | Add MCP server URL to your client | | **Auth** | API key or browser login | OAuth or API key | | **Context cost** | Minimal — just command strings | Higher — full tool schemas loaded in context | | **Multi-step tasks** | Excellent — pipe, chain, and compose commands | Can struggle with complex workflows | | **Works with** | Claude Code, Cursor, Windsurf, any terminal-based agent | Claude.ai, ChatGPT, any MCP-compatible client | You can use both. The MCP server is great for conversational AI assistants, while the CLI shines for agents that work in the terminal. Learn how to set up the Hyperline MCP server for AI assistants without terminal access. # Hyperline MCP Source: https://docs.hyperline.co/api-reference/docs/ai/mcp Connect AI assistants like Claude and Cursor to your Hyperline account through the Model Context Protocol for billing data lookups and actions. Connect your AI tools to Hyperline using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), an open standard that lets AI assistants interact with your billing data, manage customers, and automate revenue operations. ## What is Hyperline MCP? Hyperline MCP is our hosted MCP server that gives AI tools secure access to your Hyperline account. It's designed to work seamlessly with popular AI assistants like Claude, ChatGPT, Cursor, and more. ### Why use Hyperline MCP? * **Natural language billing management** — Manage customers, subscriptions, and invoices through conversational AI instead of navigating through multiple screens * **Full account access** — AI tools can search, read, create, and update records across your Hyperline account—customers, subscriptions, invoices, products, and usage data * **Easy setup** — Connect through OAuth with one-click installation for supported AI tools, or use an API token for direct authentication * **Optimized for AI** — Built specifically for AI agents with efficient data formatting and human-readable responses * **Secure by design** — Authenticates with your Hyperline credentials, with read operations auto-approved while write operations request confirmation ### What can you do with Hyperline MCP? * **Customer management** — Look up customer details, find contacts by email or name, and create new customer records * **Subscription operations** — View active subscriptions, check renewal dates, and manage subscription lifecycle * **Invoice handling** — Search invoices by status, view payment history, and track overdue payments * **Usage tracking** — Query usage data, check consumption metrics, and explore billing periods * **Revenue analytics** — Access MRR, ARR, and other key metrics through natural language queries * **Product catalog** — Browse products and pricing, understand your catalog structure ## Getting started ### Prerequisites Before connecting Hyperline MCP, ensure you have: 1. An active Hyperline account 2. An MCP-compatible AI client (Claude, ChatGPT, Cursor, VS Code, etc.) ### Authentication The Hyperline MCP server uses OAuth 2.0 for authentication. Most AI clients handle the OAuth flow automatically — you'll simply be redirected to log in with your Hyperline credentials. If your client doesn't support OAuth (for example, in a server or machine-to-machine context), you can authenticate using an API token instead. API tokens can be generated from your workspace [Settings](https://app.hyperline.co/app/settings/api). ### Connecting to Hyperline MCP Add the following server URL to your AI client: ``` https://mcp.hyperline.co/mcp ``` For sandbox environments, use `https://sandbox.mcp.hyperline.co/mcp` instead. **For Claude Desktop or Claude.ai:** 1. Open **Settings** → **Connectors** 2. Click **Add custom connector** 3. Enter a name (e.g., `hyperline`) and the URL: `https://mcp.hyperline.co/mcp` 4. Follow the OAuth prompts to log in to your Hyperline account Run the following command to add the Hyperline MCP server: ```bash theme={null} claude mcp add --transport http hyperline https://mcp.hyperline.co/mcp ``` 1. Navigate to **Settings** → **Apps** → **Advanced settings** → Enable **Developer mode** 2. Click **Create App** 3. Fill in the Name (e.g., `Hyperline`) and MCP Server URL 4. Add the MCP Server URL: `https://mcp.hyperline.co/mcp` 5. Complete the OAuth flow to authenticate with Hyperline 1. Use Command + Shift + P (Ctrl + Shift + P on Windows) to open the command palette 2. Search for "Open MCP settings" 3. Select **Add custom MCP** to open the `mcp.json` file 4. Configure the server: ```json theme={null} { "mcpServers": { "hyperline": { "url": "https://mcp.hyperline.co/mcp" } } } ``` 1. Create a `.vscode/mcp.json` file in your project 2. Configure the server: ```json theme={null} { "servers": { "hyperline": { "type": "http", "url": "https://mcp.hyperline.co/mcp" } } } ``` Add `https://mcp.hyperline.co/mcp` as a remote MCP server and complete the OAuth authentication when prompted. If your client doesn't support OAuth, use your API token for direct authentication instead. Once connected, you'll be authenticated with access to your Hyperline account data. If your MCP client runs in a server environment without a browser (e.g., a backend agent or automated pipeline), you can skip OAuth and authenticate directly with an API key. Generate an API key from your workspace [Settings](https://app.hyperline.co/app/settings/api), then pass it in the `Authorization` header when connecting to the MCP server: ``` Authorization: Bearer ``` For example, in an MCP client configuration that supports custom headers: ```json theme={null} { "mcpServers": { "hyperline": { "url": "https://mcp.hyperline.co/mcp", "headers": { "Authorization": "Bearer " } } } } ``` Keep your API key secret. Do not commit it to version control — use environment variables or a secrets manager instead. ## Multi-company access If your Hyperline user has access to multiple companies, the MCP server defaults to the first (oldest) company linked to your account. To target a specific company, include the `Hyperline-CompanyId` header in your MCP server configuration: ```json theme={null} { "mcpServers": { "hyperline": { "url": "https://mcp.hyperline.co/mcp", "headers": { "Authorization": "Bearer ", "Hyperline-CompanyId": "" } } } } ``` You can retrieve the list of companies your account has access to using the [`/v1/companies`](/api-reference/endpoints/companies/list-companies) endpoint. ## Supported tools The Hyperline MCP server exposes over 100 tools covering the full breadth of your billing operations. These include listing and retrieving customers, quotes, subscriptions, invoices, and product information, as well as actions like creating and voiding invoices, generating quotes, assigning subscriptions, querying usage data, and accessing revenue metrics — among many others. Once connected, your AI assistant automatically discovers all available tools. Simply describe what you need in natural language, and the assistant will use the right tools to get it done. ## Sample Prompts ### Customer & Account Lookup | Prompt | What it does | | --------------------------------------------- | --------------------------------------------------------- | | "Find all customers with overdue invoices" | Searches for customers with unpaid invoices past due date | | "What's the email for Acme Corp?" | Looks up contact information for a specific customer | | "Show me everything we know about customer X" | Retrieves comprehensive customer information | | "Find customers in the Enterprise plan" | Filters customers by subscription plan | | "List customers created in the last 30 days" | Shows recently acquired customers | ### Subscriptions & Billing | Prompt | What it does | | ---------------------------------------------------------- | -------------------------------------- | | "What subscriptions does Acme Corp have?" | Lists all subscriptions for a customer | | "Show me subscriptions renewing next week" | Finds upcoming renewals | | "Which customers are on the Pro plan?" | Lists customers filtered by plan | | "Create a subscription for customer X on the Starter plan" | Creates a new subscription | ### Invoices & Payments | Prompt | What it does | | -------------------------------------------- | ---------------------------------- | | "List unpaid invoices from the last 30 days" | Searches for outstanding invoices | | "What's the total amount billed this month?" | Calculates monthly billing total | | "Show me the payment history for Acme Corp" | Retrieves customer payment records | | "Find invoices over \$10,000" | Filters invoices by amount | ### Revenue Analytics | Prompt | What it does | | --------------------------------------------- | ---------------------------------- | | "What's my current MRR?" | Returns Monthly Recurring Revenue | | "Show me revenue trends for the last quarter" | Displays revenue metrics over time | | "How many active subscriptions do we have?" | Counts active subscriptions | | "What's our customer churn this month?" | Calculates churn metrics | ## Security Best Practices Treat your credentials and billing data as sensitive information. Only connect to AI applications you trust, and use sandbox credentials when experimenting. ### Tool safety Hyperline MCP uses MCP safety annotations: * **Read operations** — Auto-approved for seamless searching and viewing * **Write operations** — Request user confirmation before creating or updating data ### User permissions Hyperline MCP respects your existing user permissions. The tools available through the MCP server depend on the roles and permissions configured for your user account in your workspace [Settings](https://app.hyperline.co/app/settings/members), or API key scopes. AI assistants can only access and modify what you are authorized to do in Hyperline. You can revoke access at any time by deleting API keys or revoking user access. ### Rate limits Standard API rate limits apply to all MCP operations. See [Rate Limiting](/api-reference/docs/rate-limiting) for details. In most cases, normal conversational use stays well within rate limits. ## Troubleshooting If your AI assistant can't connect to Hyperline: 1. **Verify your credentials** — Make sure the credentials are correct and haven't been regenerated or revoked 2. **Check the environment** — Ensure you're using the correct URL for your environment (production vs sandbox) 3. **Test the connection** — Try a simple request like "List customers" to verify the connection works 4. **Check permissions** — Ensure your Hyperline user has the necessary permissions for the operations you're attempting Is something still unclear? Don't hesitate to reach out to our team via the in-app chat if you need additional support. # Build Hyperline integrations with LLMs Source: https://docs.hyperline.co/api-reference/docs/ai/overview Use Hyperline documentation and APIs with AI assistants, LLMs, and agent frameworks through CLI, MCP server, and structured machine-readable docs. You can use large language models (LLMs) to assist in building Hyperline integrations. This page explains how to access our documentation in LLM-friendly formats and how to connect AI assistants directly to your Hyperline account. ## Using documentation with LLMs ### llms.txt The [llms.txt file](https://llmstxt.org) is an industry standard that helps LLMs index content efficiently, similar to how a sitemap helps search engines. AI tools use this file to understand your documentation structure and find relevant content. We automatically host an `llms.txt` file that lists all available pages: [docs.hyperline.co/llms.txt](https://docs.hyperline.co/llms.txt) ### skill.md The [skill.md specification](https://agentskills.io/specification) is a structured, machine-readable format that describes what AI agents can accomplish with Hyperline. While `llms.txt` tells agents where to find information, `skill.md` tells them what capabilities are available, what inputs are required, and what constraints apply. We automatically host a `skill.md` file: [docs.hyperline.co/skill.md](https://docs.hyperline.co/skill.md) Agents can process this file using the [skills CLI](https://www.npmjs.com/package/skills): ```bash theme={null} npx skills add docs.hyperline.co/skill.md ``` ### Documentation MCP Server The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard that allows AI assistants to connect directly to external services. When connected to our documentation MCP server, AI tools can search our docs during response generation — providing more accurate answers than generic web searches. Connect your AI tools to our documentation MCP server at `https://docs.hyperline.co/mcp`: 1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings 2. Select **Add custom connector** 3. Add the server name (e.g., `hyperline-docs`) and URL: `https://docs.hyperline.co/mcp` 4. Select **Add** 5. When using Claude, select the attachments button (the + icon) 6. Select your MCP server Run the following command to add the Hyperline Docs MCP server: ```bash theme={null} claude mcp add --transport http hyperline-docs https://docs.hyperline.co/mcp ``` 1. Use Command + Shift + P (Ctrl + Shift + P on Windows) to open the command palette 2. Search for "Open MCP settings" 3. Select **Add custom MCP** to open the `mcp.json` file 4. Configure the server: ```json theme={null} { "mcpServers": { "hyperline-docs": { "url": "https://docs.hyperline.co/mcp" } } } ``` 1. Create a `.vscode/mcp.json` file in your project 2. Configure the server: ```json theme={null} { "servers": { "hyperline-docs": { "type": "http", "url": "https://docs.hyperline.co/mcp" } } } ``` ## Hyperline MCP Server Beyond accessing documentation, you can connect AI assistants directly to your Hyperline account to **interact with your billing data** using natural language. The Hyperline MCP server enables you to: * Query and manage customers * View and create subscriptions * Generate invoices * Access analytics and revenue metrics * And more This allows you to ask your AI assistant questions like: * "Show me all customers with overdue invoices" * "What's my current MRR?" * "Create a new subscription for customer X" Learn how to set up and use the Hyperline MCP server to connect AI assistants to your billing data. ## Hyperline CLI For AI agents that work in the terminal (Claude Code, Cursor, Windsurf), the Hyperline CLI offers a lighter, faster alternative to MCP. Commands like `hyperline customers list` are token-efficient and require no tool discovery — making agents faster and more reliable on complex, multi-step tasks. Learn how to install and use the Hyperline CLI for agent-first billing operations. # Currency amounts Source: https://docs.hyperline.co/api-reference/docs/amount Understand how Hyperline represents monetary values in the API — currency, integer amounts in minor units, and rounding rules across endpoints. Learn about [currencies support](../../docs/getting-started/currencies) in Hyperline. On the technical side, our APIs always represent currencies using their **three-letter ISO 4217 code** (see a complete list [here](https://en.wikipedia.org/wiki/ISO_4217#Active_codes_\(List_One\))), and accept and return integer amounts in the **currency's smallest unit**. For **European currencies**, this means that amounts are represented in **cents**. If you want to convert an amount with decimals into its Hyperline's format you need to multiply it by `100`. For example, an amount of €`34.17` (Euro, a two-decimal currency) will be represented in Hyperline as `3417`. Hyperline also supports **zero-decimal currencies** and **three-decimal currencies**. In this case, you need to apply the right multiplier (or none). For example, an amount of `F CFA 12065` (West African CFA franc, a zero-decimal currency) will be represented in Hyperline as `12065`. # Authentication Source: https://docs.hyperline.co/api-reference/docs/authentication Authenticate to the Hyperline API with bearer tokens, manage API keys, and configure secure access for production and sandbox environments. The Hyperline API requires either an **API key** or an **access token** to identify and authorise calls. API keys are associated with a single Hyperline account, and an access token represents delegated access to a specific account (used for [third-party app](./third-party-app)). You can have more than one token or key at any point in time. Those tokens are able to authenticate to Hyperline and perform actions on your account so it's important that you keep them safe in the same way that you would a password. ## Manage API keys ### How to generate an API key Generating an **API key** is very simple and allow you to use Hyperline's API or integration such as Zapier. As a Hyperline's admin: 1. Go to your workspace [Settings](https://app.hyperline.co/app/settings/api), section API 2. Click on `+ New API key` 3. Add a name for this key, and select the appropriate scopes (in most cases you'll need right/write accesses) 4. Copy the key and it in a safe space, you won't be able to see it later in Hyperline API keys are prefixed either with `prod_` or `test_` to easily identify and distinguish them between environments. ### Using authentication token API keys or access tokens must be provided with every API call, specified in the `Authorization` header after a `Bearer` prefix. All requests happen using HTTPS. For example: ```sh theme={null} curl -H "Authorization: Bearer " https://api.hyperline.co/v1/customers ``` We also support HTTP Basic Authentication, where the `username` is the API key and the `password` is left blank, but we recommend using Bearer Authentication because it's simpler for debugging. ### Keeping your data safe Your API keys should be treated as **highly sensitive information** - think of a token like a password. You should only give tokens to services you fully trust. If leaked, tokens could be used maliciously - they can provide someone with access to all of your Hyperline data. If you suspect a token has been compromised, revoke it and replace it with a new one. Tokens should never be shared with support teams or your customers. ### Revoke a key Workspace admins can permanently revoke tokens from the [API Settings](https://app.hyperline.co/app/settings/api) in Hyperline. To revoke a token, click on the `…` icon on the line of the key name, then `Delete` to permanently delete it. A deleted key cannot be recovered. # Dates & timezones Source: https://docs.hyperline.co/api-reference/docs/dates-and-timezones Understand how Hyperline represents dates, datetimes, and timezones across the API — ISO 8601 formatting, UTC defaults, and billing-cycle conventions. # Date Format and Timezone Handling All dates in the Hyperline API are handled in UTC (Coordinated Universal Time). When sending dates to the API, you must convert your local timezone dates to UTC. Similarly, all dates returned by the API will be in UTC format. ## Working with Customer Timezones When creating subscriptions for customers in specific timezones, you'll need to convert the desired local time to UTC before sending it to the API. ### Examples Let's say you want to create a subscription that starts at midnight (00:00) in Paris timezone (Europe/Paris): ```javascript theme={null} // Example 1: January 1st, 2024 at 00:00 Paris time // Paris is UTC+1 in winter, so we need to convert to UTC (23:00 previous day) "2023-12-31T23:00:00Z" // Example 2: July 1st, 2024 at 00:00 Paris time // Paris is UTC+2 in summer (due to daylight saving), so we need to convert to UTC (22:00 previous day) "2024-06-30T22:00:00Z" ``` Note that the `Z` suffix in the date string indicates that the timestamp is in UTC. ## Best Practices * Always use ISO 8601 format for dates * Include the UTC indicator (`Z`) in your timestamps * Consider daylight saving time when converting from local timezones * Use a reliable date library (like `date-fns` or `luxon`) to handle timezone conversions # Error handling Source: https://docs.hyperline.co/api-reference/docs/error-handling Handle Hyperline API errors safely: HTTP status codes, error response payloads, validation failures, retry guidance, and common troubleshooting. The Hyperline API uses conventional HTTP response codes to indicate the success or failure of an API request. This page details how to handle errors effectively and what to expect in error responses. ## HTTP Status Codes The API uses standard HTTP status codes to indicate the success or failure of requests: * **2xx Success**: The request was successful * **4xx Client Error**: The request was invalid or cannot be processed * **5xx Server Error**: An internal server error occurred ## Error Response Format When an error occurs, the API returns a JSON response with a `message` property containing a human-readable description of the error: ```json theme={null} { "message": "The requested resource was not found" } ``` ## Common Error Codes ### 400 Bad Request The request was malformed or contains invalid parameters. ```json theme={null} { "message": "Cannot assign a subscription to a customer without a currency set" } ``` Common validation errors include: * Missing required fields * Invalid parameter values ### 401 Unauthorized The request lacks valid authentication credentials. ```json theme={null} { "message": "Missing authentication token" } ``` ### 404 Not Found The requested resource was not found. ```json theme={null} { "message": "Product not found" } ``` ### 429 Too Many Requests The request rate limit has been exceeded. See [Rate Limiting](./rate-limiting) for more details. ## Getting Help If you encounter an error that you cannot resolve, please: 1. Check the error message for guidance 2. Verify your request format and parameters 3. Ensure your authentication credentials are valid 4. Contact our support team with the error details and request information # Getting started with the Hyperline API Source: https://docs.hyperline.co/api-reference/docs/getting-started Start building with the Hyperline API: create your API key, make your first request, explore key endpoints, and integrate billing into your product. We offer you a complete set of resources, including APIs, a webhook system, low-code solutions, and developer tools, to facilitate the creation of a full technical integration seamlessly. However, our main principle is to minimize the technical workload on your end and abstract away the complexities of managing a billing system, allowing you to focus on delivering your core product value. The Hyperline API is structured following REST principles and utilizes JSON-encoded data payloads. It adheres to industry standards and strives to deliver the most user-friendly interface possible, with straightforward operations, detailed error messages, and predictable behavior. This ensures that integrating with us is an effortless process. **Sandbox environment** In order to experiment, we provide you with a test mode (sandbox environment) where no real money or operations are involved. This allows you to test any flows you want without affecting your live data or interact with the banking networks. To do this, you can switch on the **test mode** option on your Hyperline account. ## Not a developer? Hyperline offers plenty of options to get started with pricing and billing capabilities without any code implementation. For this, you can check out our [product documentation](../../docs). ## OpenAPI specification The Hyperline API is fully documented using the OpenAPI specification. You can retrieve the complete OpenAPI file to generate client libraries, import into API testing tools, or integrate with your development workflow at: [https://api.hyperline.co/openapi](https://api.hyperline.co/openapi). ## Services endpoints ### Production environment | Service | Base URL | | -------------------- | ------------------------------------------------------------ | | Main API | [https://api.hyperline.co](https://api.hyperline.co) | | Events ingestion API | [https://ingest.hyperline.co](https://ingest.hyperline.co) | | MCP server | [https://api.hyperline.co/mcp](https://api.hyperline.co/mcp) | | Browser application | [https://app.hyperline.co](https://app.hyperline.co) | ### Sandbox environment (test mode) | Service | Base URL | | -------------------- | ---------------------------------------------------------------------------- | | Main API | [https://sandbox.api.hyperline.co](https://sandbox.api.hyperline.co) | | Events ingestion API | [https://sandbox.ingest.hyperline.co](https://sandbox.ingest.hyperline.co) | | MCP server | [https://sandbox.api.hyperline.co/mcp](https://sandbox.api.hyperline.co/mcp) | | Browser application | [https://sandbox.app.hyperline.co](https://sandbox.app.hyperline.co) | # Idempotent requests Source: https://docs.hyperline.co/api-reference/docs/idempotent-requests Safely retry Hyperline API requests using idempotency keys to avoid duplicate operations across customer, subscription, and payment endpoints. The Hyperline API supports idempotency, allowing you to safely retry requests without accidentally performing the same operation twice. This is especially useful when a network error or timeout prevents you from knowing whether a request succeeded. ## How it works Pass a unique `Idempotency-Key` header with any mutating request (`POST`, `PUT`, `PATCH`). If the request succeeds, Hyperline caches the response for **24 hours**. Any subsequent request with the same key returns the cached response instead of re-executing the operation. ``` POST /v1/invoices Idempotency-Key: a8098c1a-f86e-11da-bd1a-00112444be1e ``` ## Generating idempotency keys Use a V4 UUID or any sufficiently random string (at least 16 characters). The key must be unique per **operation intent** — generate a new key for each distinct operation. ```javascript theme={null} const { randomUUID } = require("crypto"); const response = await fetch("https://api.hyperline.co/v1/invoices", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Idempotency-Key": randomUUID(), "Content-Type": "application/json", }, body: JSON.stringify({ customer_id: "cus_123", ... }), }); ``` ## Behavior | Scenario | Result | | ----------------------------------------------- | --------------------------------------------- | | First request with a key | Executes normally, caches response | | Retry with same key and same body | Returns cached response (no re-execution) | | Request with same key but different body or URL | Returns `417 Expectation Failed` | | Concurrent requests with the same key | Returns `409 Conflict` for the second request | ## Error responses **409 Conflict - Request in progress** A request with the same idempotency key is currently being processed. Wait for the original request to complete before retrying. **417 Expectation Failed - Intent mismatch** A completed request exists for this key, but the new request has a different method, URL, or body. This usually means you accidentally reused a key for a different operation. Generate a new key for the new request. ## Best practices * **Generate keys client-side** before sending the request, so retries reuse the same key. * **One key per operation** — do not reuse a key for logically different requests. * **Retry on network errors** — if a request times out, retry with the same key. The operation will not be duplicated. * **Do not retry on 4xx errors** (except 409/429) — these indicate a problem with your request that retrying won't fix. ## Supported endpoints Idempotency keys are accepted on all mutating endpoints (`POST`, `PUT`, `PATCH`). They are ignored on `GET` requests since those are already safe to retry. # Pagination and filtering Source: https://docs.hyperline.co/api-reference/docs/pagination Paginate and filter Hyperline API list endpoints with cursor-based pagination, page sizes, and per-endpoint filter parameters for efficient queries. All list requests can be paginated and filtered using the same query format. For convenience, we've made sure all *list-based* endpoints returned data with the same structure. ## Pagination We're using 2 parameters for pagination: * `take` is the number of items the API will return, default is **50**, max is **100** * `skip` is the number of items the API will skip, default is **0** So if you want to get the first 50 items of a list, you don't need any parameters. If you need items from the 350th to the 425th, you'll use `take=75` and `skip=350`. Here's an example with the customer list: ```sh theme={null} curl --request GET \ --url 'https://api.hyperline.co/v1/customers?take=10&skip=10' \ --header 'Authorization: Bearer ' ``` The API will always return a similarly shaped payload containing: * `data` the items you requested * `meta` the contextual information (total number of items, number selected...) For instance for customers: ```json theme={null} { "meta": { "total": 2, "taken": 2, "skipped": 0 }, "data": [ { "id": "cus_3fhwCWcL0Rx5MQ" // other properties }, { "id": "cus_9huL9ahn7KQqHo" // other properties } ] } ``` ## Sorting Some list endpoints support sorting results using the `sort` and `order` query parameters: * `sort` specifies the field to sort by (e.g., `created_at`, `emitted_at`) * `order` specifies the sort direction: `asc` (ascending) or `desc` (descending) For example: ```sh theme={null} curl --request GET \ --url 'https://api.hyperline.co/v1/invoices?sort=emitted_at&order=desc' \ --header 'Authorization: Bearer ' ``` Not all list endpoints support sorting. Refer to each endpoint's documentation to see which sort fields are available. ## Filtering Our API is offering many filtering capabilities so you can always find what you're looking for. Filters are passed as query parameters using a common pattern. `fieldName__operator=value` For instance: * `GET /v1/customers?name__contains=instagram` will return all customers with the name containing instagram * `GET /v1/customers?id__in=123,456,789` will return customers with ID equals to 123, 456, or 789 ## List of available operators * `equals` (or just `=xxx`) * `not` * `lt` * `lte` * `gt` * `gte` * `contains` * `startsWith` * `endWith` * `in` * `notIn` * `isNull` * `isNotNull` Numerical operators can be applied to numbers or dates. Not all fields can be filtered, please refer to each model in the API Reference to see which ones are available. # Rate limiting Source: https://docs.hyperline.co/api-reference/docs/rate-limiting Understand Hyperline API rate limits, response headers, and best practices to handle 429 responses with retries and exponential backoff strategies. Our API implements rate limiting to ensure fair usage and protect the system from abuse. This page details our rate limiting policies and how to handle them effectively. ## Rate limits ### Core API | Operation Type | Limit | Window | | -------------------------------- | ----- | ---------- | | Read (GET) | 200 | 10 seconds | | Write (POST, PUT, PATCH, DELETE) | 50 | 10 seconds | ### Events ingestion API The events ingestion API has separate rate limits: | Operation Type | Limit | Window | | -------------- | ----- | ---------- | | All requests | 1,000 | 10 seconds | Additionally, the following payload size limits apply: * **`POST /v1/events/batch`**: maximum of 5,000 events per request * **`DELETE /v1/events`**: maximum of 5,000 event IDs per request ## Rate Limit Headers API responses include the following rate limit headers: * `X-RateLimit-Limit`: The maximum number of requests allowed in the current window * `X-RateLimit-Remaining`: The number of requests remaining in the current window * `X-RateLimit-Reset`: The date and time when the rate limit window resets * `Retry-After`: The minimum number of seconds to wait before retrying (only when the limit has been reached) ## Handling Rate Limits When you exceed the rate limit, the API will return a **429 Too Many Requests** HTTP status code. The response body will be: ```json theme={null} Too many requests ``` ### Best Practices 1. **Monitor Rate Limits**: Track the `X-RateLimit-Remaining` header to anticipate when you're approaching the limit 2. **Implement Backoff**: When you receive a 429 response: * Wait until the date specified in the `X-RateLimit-Reset` header * Consider implementing exponential backoff for retries 3. **Batch Requests**: When possible, combine multiple operations into a single request 4. **Caching**: Cache responses when appropriate to reduce the number of API calls ## Example Response Headers Rate limit not exceeded: ```text theme={null} HTTP/1.1 200 OK X-RateLimit-Limit: 200 X-RateLimit-Remaining: 150 X-RateLimit-Reset: 2025-04-15T10:18:08.107Z ``` Rate limit exceeded: ```text theme={null} HTTP/1.1 429 Too Many Requests X-RateLimit-Limit: 200 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 2025-04-15T10:18:08.107Z Retry-After: 5 ``` ## Custom Rate Limits If your application requires higher rate limits, please contact our support team. We'll work with you to establish appropriate limits based on your use case. # React components Source: https://docs.hyperline.co/api-reference/docs/react-components Embed Hyperline checkout, customer portal, and payment method components directly in your React application with the official React SDK. Hyperline provides built-in React components to: * For each customer, display their subscriptions * preview and update the payment method * list and download invoices * list and update billing information This doc assumes that you already have a basic working knowledge of [React](https://react.dev/) and that you have already set up a React project. ## Getting started First install the `@hyperline/react-components` NPM package. ```sh Install the package theme={null} npm install @hyperline/react-components ``` To allow a customer to see its Hyperline's data, you need to generate a unique authentication token on your server side. You can use our API and the [create auth token endpoint](../../api-reference/endpoints/integrations/create-component-token) for this. ```sh cURL theme={null} curl -X POST 'https://api.hyperline.co/v1/integrations/components/token' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ # You can create an [api key here](https://app.hyperline.co/app/settings/api) -d '{ "customer_id": "" }' ``` Then, integrate the React components. You will most likely generate a new token every time your customer access the page. ```ts theme={null} import { Subscriptions, PaymentMethod } from "@hyperline/react-components"; export default function HyperlineSubscriptions() { return ( ", mode: "production" // if you're using our sandbox, set "sandbox" here locale: "en" // optional }} /> ); } export default function HyperlinePaymentMethod() { return ( ", mode: "production" // if you're using our sandbox, set "sandbox" here locale: "en" // optional }} onPaymentMethodCreated={() => do something} // optional, from 0.2.20 onPaymentMethodDeleted={() => do something} // optional, from 0.2.20 /> ); } ``` ## Components ### Subscriptions List all active subscriptions ```tsx theme={null} " }} /> ``` ### Subscription Display a subscripton by ID ```tsx theme={null} " }} /> ``` ### InvoicesList List and download all invoices and refunds ```tsx theme={null} " }} /> ``` ### PaymentMethod Display the current payment method, delete it if allowed, or add a new payment method ```tsx theme={null} " }} /> ``` ### CustomerBillingInfoForm Display a form with all billing info, with an optional callback when the form has been successfully saved. ```tsx theme={null} {}} options={{ token: "" }} /> ``` ## Component options When using the components, you will need to provide an `options` prop with the following parameters: | name | Description | Type | Default value | Required | | ---------- | ----------------------------------------- | --------------------- | ------------- | -------- | | token | The token specific to your customer | string | | ☑️ | | mode | Which Hyperline environment are you using | production \| sandbox | production | | | appearance | Customise the appearance of the component | Object | | | ### Appearance You can change the colors and fonts of the component. ```tsx theme={null} ", appearance: { variables: { borderRadius: "10px", colorBackground: "#000000", colorPrimary: "#e1e2f3", colorPrimaryHover: "#d0d1e5", colorPrimaryDisabled: "#667", colorBorder: "#445", colorText: "#f1f2f3", colorTextSecondary: "#dededf", fontFamily: "sacramento" }, fonts: [ { src: "url(https://fonts.gstatic.com/s/sacramento/v13/buEzpo6gcdjy0EiZMBUG4C0f_f5Iai0.woff2)", family: "sacramento" } ] } }} /> ``` ### Variables They are meant to customise all elements at once. | Variable name | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------ | | `borderRadius` | Change the roundness of the elements: Buttons, tables, ... | | `colorBackground` | Most elements have a transparent background. In other cases, you can customise the background color of the element | | `colorPrimary` | Color used for buttons and accent text | | `colorPrimaryHover` | Hover color for buttons | | `colorPrimaryDisabled` | Color of disabled buttons | | `colorBorder` | The color of all our regular borders | | `colorText` | Default text color | | `colorTextSecondary` | Text color of secondary text | | `fontFamily` | Font used. If you need to import a font, please read the next section | ### Fonts Set your application's font. * `src` Url of the font file * `family` Name of the font - this is the name you'll use for the `fontFamily` variable ```ts theme={null} ``` # API upgrades Source: https://docs.hyperline.co/api-reference/docs/upgrades Track Hyperline API changes, deprecations, and upgrades — see what's changed across versions and plan migrations for breaking changes safely. # May 29, 2026 * Added `/v1/transactions/{id}/refund` POST endpoint # May 27, 2026 * Major * Added a hard cap to offset pagination on `/v1/customers` GET and `/v1/invoices` GET endpoints. Requests with `skip + take` greater than `10000` now return `400`; use `/v2/customers` GET or `/v2/invoices` GET cursor pagination for deeper queries. * Draft quote subscription configuration can no longer be updated with `/v2/subscriptions/{id}` PUT endpoint. Use `/v1/quotes/{id}` PATCH endpoint with the `subscription` payload instead. * Added `/v1/quotes/{id}` PATCH endpoint * Added `/v1/aggregators/{id}/usage` GET endpoint * Added `/v1/aggregators/{id}/usage/timeseries` POST endpoint * Added `/v1/aggregators/{id}/usage/group-by-customer` POST endpoint * Added `/v1/aggregators/{id}/usage/events` POST endpoint * Added `/v1/customers/{id}/usage` GET endpoint * Added `/v1/customers/{id}/usage/{aggregator_id}` GET endpoint * Added `/v1/customers/{id}/usage/{aggregator_id}/timeseries` POST endpoint * Added `/v1/customers/{id}/usage/{aggregator_id}/events` POST endpoint # May 26, 2026 * Added `Invoice.custom_properties` on `/v1/invoices` GET, POST endpoints * Added `Invoice.custom_properties` on `/v1/invoices/{id}` GET, PATCH endpoints * Added `Invoice.custom_properties` support on `/v1/invoices/batch` POST endpoint * Added `Invoice.custom_properties` support on `/v2/invoices/batch` POST endpoint * Added `/v1/invoices/{id}/events` GET endpoint * Added `Subscription.cancellation_source` on `/v2/subscriptions` GET endpoint * Added `Subscription.cancellation_source` on `/v2/subscriptions/{id}` GET endpoint # May 25, 2026 * Added `/v2/customers` GET endpoint * Added `/v2/customers/{id}` GET endpoint * Deprecation warning * Deprecating `/v1/customers` GET endpoint in favor of `/v2/customers` GET endpoint * Deprecating `/v1/customers/{id}` GET endpoint in favor of `/v2/customers/{id}` GET endpoint # May 21, 2026 * Added `trigger_refund` and `refund_method` on `/v1/invoices/{id}/credit-notes` POST endpoint * Added `WalletSettings.credit_note_refund_to_wallet_enabled` on `/v1/wallets/settings` GET, PATCH endpoints. When enabled, credit note refunds default to the customer's wallet when `refund_method` is omitted. # May 20, 2026 * Added `/v2/invoices` GET endpoint * Added `/v2/invoices/{id}` GET endpoint * Deprecation warning * Deprecating `/v1/invoices` GET endpoint in favor of `/v2/invoices` GET endpoint * Deprecating `/v1/invoices/{id}` GET endpoint in favor of `/v2/invoices/{id}` GET endpoint # April 16, 2026 * Major * Removed `SubscriptionProduct.charging_method` from regular (non-connected) seat products on `/v2/subscriptions` GET endpoint. Field is now only present for connected seat products. * Added `Subscription.invoice_schedule` on `/v2/subscriptions` GET, POST, PUT endpoints * Added `SubscriptionProduct.seat_invoicing_schedule` on `/v2/subscriptions` GET, POST, PUT endpoints # April 15, 2026 * Added `Subscription.products` on `/v2/subscriptions` GET endpoint * Added `Subscription.coupons` on `/v2/subscriptions` GET endpoint # April 10, 2026 * Added `/v1/price-books` GET endpoint * Added `/v1/price-books/{id}` GET endpoint * Added `/v1/price-books` POST endpoint * Added `/v1/price-books/{id}` PUT endpoint * Added `/v1/price-books/{id}` DELETE endpoint * Added `/v1/price-books/{id}/products` POST endpoint * Added `/v1/price-books/{id}/products/{productId}` DELETE endpoint * Added `/v1/users` GET endpoint * Added `/v1/users/{id}` GET endpoint * Added `/v1/users/roles` GET endpoint * Added `/v1/users/roles/{id}` GET endpoint # April 8, 2026 * Added `Quote.require_tax_id` on `/v1/quotes` GET endpoint * Added `Quote.require_tax_id` on `/v1/quotes/{id}` GET endpoint * Added `Quote.require_tax_id` on `/v1/quotes` POST endpoint * Added `SubscriptionTransition.actor` on `/v2/subscriptions/{id}` GET endpoint * Added `SubscriptionTransition.actor` on `/v2/subscriptions` GET endpoint * Added `PriceConfiguration.aggregator_filter_id` on `/v1/price-configurations` GET endpoint * Added `PriceConfiguration.aggregator_filter.aggregator_id` on `/v1/price-configurations` GET endpoint * Added `aggregator_filter_id` support on `/v1/products` PUT endpoint for dynamic price configurations # April 2, 2026 * Added `Customer.segment_ids` on `/v1/customers` GET endpoint * Added `Customer.segment_ids` on `/v1/customers/{id}` GET endpoint # March 30, 2026 * Added `Aggregator.thresholds` on `/v1/aggregators` GET, POST, PUT endpoints * Added `Aggregator.default_interval_count` on `/v1/aggregators` GET, POST, PUT endpoints * Added `Aggregator.default_interval_period` on `/v1/aggregators` GET, POST, PUT endpoints # March 20, 2026 * Major * Changed `PaymentMethod.last_4_digits` from number to string on `/v1/customers/{id}/payment-methods` GET endpoint * Changed `PaymentMethod.last_4_digits` from number to string on `/v1/customers/{id}/payment-methods/{paymentMethodId}` GET endpoint * Changed `PaymentMethod.last_4_digits` from number to string on `/v1/customers/{id}/payment-methods` POST endpoint * Added `Subscription.custom_properties` on `/v2/subscriptions/{id}` PUT endpoint * Added `Provider.slug` on provider endpoints # March 19, 2026 * Major * Changed `Quote.display_price_tiers` from boolean to enum on `/v1/quotes` GET, POST endpoints. Accepts `all`, `matching`, or `none`. Boolean values are still accepted for backward compatibility (`true` → `all`, `false` → `matching`) # March 18, 2026 * Added `/v1/subscriptions/{id}/valuation` GET endpoint * Added `/v1/quotes/{id}/valuation` GET endpoint * Added `/v1/customers/{id}/valuation` GET endpoint # February 18, 2026 * Added `Transaction.integrations` on `/v1/invoices` GET endpoint * Added `Transaction.integrations` on `/v1/invoices/{id}` GET endpoint * Added `Transaction.integrations` on `/v1/invoices` POST endpoint * Added `Transaction.integrations` on `/v2/invoices/simulate` POST endpoint * Added `sort` and `order` query params on `/v1/invoices` GET endpoint (supports `created_at` and `emitted_at`) * Deprecation warning * Deprecating `Transaction.provider_id` in favor of `Transaction.integrations[].entity_id` ## February 10, 2026 * Added `/v2/wallets` GET endpoint * Major Deprecation warning * Deprecating `/v1/wallets` GET endpoint ## February 9, 2026 * Added `/v1/events` GET endpoint * Added `Invoice.line_items[].original_line_item_id` on `/v1/invoices` GET endpoint * Added `Invoice.line_items[].original_line_item_id` on `/v1/invoices/{id}` GET endpoint ## February 5, 2026 * Added `/v2/invoices/batch` POST endpoint * Added `invoice.batch.creation_succeeded`, `invoice.batch.creation_failed` webhooks ## January 29, 2026 * Added `/v1/wallets/{id}/transactions/{transactionId}/revert` POST endpoint * Added `WalletTransaction.original_transaction_id` on `/v1/wallets/{id}/transactions` GET endpoint * Added `WalletTransaction.reverted_by` on `/v1/wallets/{id}/transactions` GET endpoint ## January 28, 2026 * Added `Invoice.line_items[].display_unit_amount` on `/v1/invoices` GET, POST endpoints * Added `Invoice.line_items[].display_unit_amount` on `/v1/invoices/{id}` GET, PATCH endpoints * Added `Invoice.line_items[].display_service_period` on `/v1/invoices` GET, POST endpoints * Added `Invoice.line_items[].display_service_period` on `/v1/invoices/{id}` GET, PATCH endpoints ## January 26, 2026 * Added `Customer.custom_payment_initiation_delay` on `/v1/customers` GET, POST endpoints * Added `Customer.custom_payment_initiation_delay` on `/v1/customers/{id}` GET, PUT endpoints * Added `InvoicingEntity.registration_number` on `/v1/invoicing-entities` GET, POST endpoints * Added `InvoicingEntity.registration_number` on `/v1/invoicing-entities/{id}` GET, PUT endpoints ## January 11, 2026 * Added `Subscription.display_quote_value`, `Subscription.display_taxes`, `Subscription.display_price_tiers`, `Subscription.display_phase_value`, `Subscription.display_first_invoice_amount`, `Subscription.display_documents_in_preview`, `Subscription.display_subscription_on_update` on `/v2/subscriptions` GET, POST endpoints ## January 9, 2026 * Added `/v2/subscriptions/transitions` POST endpoint * Added `/v2/subscriptions/transitions` GET endpoint * Added `/v2/subscriptions/transitions/{id}` GET endpoint * Added `/v2/subscriptions/transitions/{id}/cancel` POST endpoint * Added `subscription_transition.completed` webhook ## December 30, 2025 * Added `auto_load_threshold` field to wallet endpoints ## December 18, 2025 * Added `wallet.low_projected_balance` webhook ## December 11, 2025 * Added `Customer.tax_ids` and `Customer.tax_rate_custom` on `/v1/customers` GET, POST endpoints * Added `Customer.tax_ids` and `Customer.tax_rate_custom` on `/v1/customers/{id}` GET, PUT endpoint * Added `Invoice.customer.tax_id` on `/v1/invoices` GET endpoint * Added `Invoice.customer.tax_id` on `/v1/invoices/{id}` GET endpoint * Major Deprecation warning * Deprecating `Customer.vat_number` and `Customer.vat_number_valid` in favor of `Customer.tax_ids` * Deprecating `Customer.vat_rate_custom` in favor of `Customer.tax_rate_custom` * Deprecating `Invoice.customer.vat_number` in favor of `Invoice.customer.tax_id` ## December 4, 2025 * Added `custom_properties` query param on `/v2/subscriptions` GET endpoint ## December 1, 2025 * Added `Customer.shipping_address` on `/v1/customers` GET, POST endpoints * Added `Customer.shipping_address` on `/v1/customers/{id}` GET, PUT endpoints ## November 28, 2025 * Added `Invoice.public_url` on `/v1/invoices/{id}` GET endpoint ## November 19, 2025 * Added `/v1/exports` POST endpoint * Added `/v1/exports/{id}` GET endpoint * Added `/v1/exports/{id}/download` GET endpoint ## October 31, 2025 * Added `/v1/customers/{id}/credits/{id}` PUT endpoint ## October 23, 2025 * Added `Invoice.coupons` on `/v1/invoices` POST endpoint * Added `Invoice.coupons` on `/v1/invoices/{id}` PATCH endpoint * Added `Invoice.coupons` on `/v1/invoices/batch` POST endpoint ## October 16, 2025 * Added `Coupon.product_ids` on `/v1/coupons` GET endpoint * Added `Coupon.product_ids` on `/v1/coupons` POST endpoint * Added `Coupon.product_ids` on `/v1/coupons/{id}` GET endpoint * Added `Coupon.product_ids` on `/v1/coupons/{id}` PUT endpoint * Added `/v1/subscriptions/templates` GET endpoint * Added `/v1/subscriptions/templates/{id}` GET endpoint * Added `Subscription.template_id` on `/v2/subscriptions` POST endpoint * Added `Subscription.template_configuration_id` on `/v2/subscriptions` POST endpoint * Major Deprecation warning * Deprecating `/v1/plans` GET endpoint * Deprecating `/v1/plans/{id}` GET endpoint ## October 1, 2025 * Added `product_id`, `customer_id`, `updated_at` query params on `/v1/customers/credits` GET endpoint ## September 30, 2025 * Added `Customer.is_government_affiliated` on `/v1/customers` POST, GET, PUT endpoints ## September 26, 2025 * Added `/v1/customers/credits` GET endpoint * Added `Credit.auto_topup` on `/v1/customers/{id}/credits` POST, GET endpoints * Added `Credit.auto_topup` on `/v1/customers/{id}/credits/{creditId}` GET endpoint ## September 23, 2025 * Added `/v1/quotes/{id}/approve` POST endpoint ## September 19, 2025 * Added `Customer.integrations` on `/v1/customers` GET endpoint ## September 16, 2025 * Added `period_start` and `period_end` query params on `/v1/invoices` GET endpoint ## September 15, 2025 * Added `Subscription.activation_strategy` on `/v2/subscriptions` GET endpoint ## September 11, 2025 * Added `Subscription.phases[].do_not_invoice_phase` on `/v2/subscriptions/{id}` GET endpoint * Added `Subscription.phases[].do_not_invoice_phase` on `/v2/subscriptions` POST endpoint * Added `Subscription.phases[].do_not_invoice_phase` on `/v2/subscriptions/{id}` PUT endpoint ## September 10, 2025 * Added `/v1/invoices/{id}/uncollectible` POST endpoint ## September 5, 2025 * Added `Subscription.phases` on `/v2/subscriptions/{id}` PUT endpoint ## August 27, 2025 * Added `Invoice.source` on `/v1/invoices` GET endpoint * Added `Invoice.source` on `/v1/invoices/{id}` GET endpoint ## August 25, 2025 * Added `/v1/bank-accounts` GET endpoint * Added `/v1/bank-accounts/{id}` GET endpoint ## August 18, 2025 * Added `/v1/subscriptions/{id}/simulate-updates` POST endpoint * Added `plan.created`, `plan.updated` and `plan.deleted` webhooks ## August 8, 2025 * Added `Quote.updated_at` on `/v1/quotes` GET endpoint * Added `Quote.updated_at` on `/v1/quotes/{id}` GET endpoint * Added `PriceConfiguration.price_book_id` on `/v1/price-configurations` GET endpoint ## July 21, 2025 * Added `Subscription.crm_opportunity_id` on `/v2/subscriptions` POST endpoint * Added `Subscription.crm_opportunity_id` on `/v2/subscriptions/{id}` PUT endpoint ## July 17, 2025 * Added `reason` on `/v1/subscriptions/{id}/cancel` POST endpoint * Added `Subscription.cancellation_reason` on `/v2/subscriptions` GET endpoint * Added `Subscription.cancellation_reason` on `/v2/subscriptions/{id}` GET endpoint ## July 11, 2025 * Added `/v1/customers/{id}/payment-methods` POST endpoint * Added `Transaction.provider_name` and `Transaction.provider_transaction_id` on `/v1/invoices/{id}/transactions` POST endpoint ## July 7, 2025 * Added `/v1/files` GET, POST endpoints * Added `/v1/files/{id}` DELETE endpoint * Added `/v1/files/{id}/download` GET endpoint * Added `Invoice.properties` on `/v1/invoices` GET, POST endpoints * Added `Invoice.properties` on `/v1/invoices/{id}` GET, PATCH endpoints ## July 3, 2025 * Added `/v1/subscriptions/{id}/renew` POST endpoint ## June 27, 2025 * Added `Invoice.coupons` and `Invoice.transactions` on `/v1/invoices` GET endpoint ## June 18, 2025 * Added `Subscription.name` on `/v2/subscriptions/{subscriptionId}` GET endpoint * Added `Subscription.name` on `/v2/subscriptions` GET endpoint ## June 13, 2025 * Added `Subscription.generate_document`, `Subscription.document_name` and `Subscription.add_vat_to_document` on `/v2/subscriptions` POST endpoint ## June 11, 2025 * Added `/v1/invoices/{id}/credit-notes` POST endpoint * Added `Invoice.integrations` on `/v1/invoices/{id}` GET endpoint * Added `Customer.integrations` on `/v1/customers/{id}` GET endpoint * Added `PaymentMethod.integration` on `/v1/customers/{id}/payment-methods/{id}` GET endpoint * Major Deprecation warning * Deprecating `Customer.providers` in favor of `Customer.integrations` ## June 6, 2025 * Added `/v1/price-configurations` GET endpoint * Added `/v1/price-configurations/{id}` DELETE endpoint ## May 16, 2025 * Added `purchase_order` query param on `/v2/subscriptions` GET endpoint ## May 9, 2025 * Added `/v1/promotion-codes` GET, POST endpoints * Added `/v1/promotion-codes/{id}` GET, PATCH, DELETE endpoints ## April 30, 2025 * Added `Subscription.contract_terms` on `/v2/subscriptions/{subscriptionId}` GET endpoint * Added `Subscription.contract_terms` on `/v2/subscriptions` POST endpoint * Added `Quote.subscription.contract_terms` on `/v1/quotes` POST endpoint * Added `Invoice.bank_account_id` on `/v1/invoices/{id}` GET endpoint * Added `Invoice.bank_account_id` on `/v1/invoices/{id}` PATCH endpoint * Added `Invoice.payment_method_type` on `/v1/invoices/{id}` PATCH endpoint * Added `Invoice.payment_method_id` on `/v1/invoices/{id}` PATCH endpoint ## April 18, 2025 * Added `Subscription.billing_cycle_alignment` on `/v2/subscriptions` POST endpoint ## April 8, 2025 * Added `Invoice.type` on `/v1/invoices` POST endpoint * Added `Invoice.type` on `/v1/invoices/{id}` PATCH endpoint * Added `Invoice.document_name` on `/v1/invoices` POST endpoint * Added `Invoice.document_name` on `/v1/invoices/{id}` PATCH endpoint * Added `Invoice.tax_scheme` on `/v1/invoices` POST endpoint * Added `Invoice.tax_scheme` on `/v1/invoices/{id}` PATCH endpoint * Added `Invoice.line_items` on `/v1/invoices/{id}` PATCH endpoint ## April 4, 2025 * Added `Subscription.trial` on `/v2/subscriptions` POST endpoint * Added `Quote.subscription.trial` on `/v1/quotes` POST endpoint * Major Deprecation warning * Deprecating `Subscription.trial_ends_at` and `Subscription.trial_delay_first_invoice` in favor of `Subscription.trial` * Deprecating `Quote.subscription.trial_ends_at` and `Quote.subscription.trial_delay_first_invoice` in favor of `Quote.subscription.trial` ## March 31, 2025 * Added `/v1/invoices/{id}/charge` POST endpoint * Added `Invoice.transactions[].chargeback` on `/v1/invoices/{id}` GET endpoint * Added `Subscription.phases[].billing_cycle_alignment` on `/v2/subscriptions/{subscriptionId}` GET endpoint * Added `SubscriptionPhase.billing_cycle_alignment` on `/v2/subscriptions/{subscriptionId}/phases` GET endpoint * Added `SubscriptionPhase.billing_cycle_alignment` on `/v2/subscriptions/{subscriptionId}/phases/{phaseId}` GET endpoint * Added `Subscription.phases[].billing_cycle_alignment` on `/v2/subscriptions` POST endpoint * Added `Quote.subscription.phases[].billing_cycle_alignment` on `/v1/quotes` POST endpoint * Added `subscription.reinstated` webhook ## March 24, 2025 * Added `PaymentMethod.status` on `/v1/customers/{id}/payment-methods` GET endpoint * Added `PaymentMethod.status` on `/v1/customers/{id}/payment-methods/{paymentMethodId}` GET endpoint * Added `Customer.price_book_id` on `/v1/customers` GET endpoint * Added `Customer.price_book_id` on `/v1/customers/{id}` GET endpoint ## March 11, 2025 * Added `/v1/products/{id}/archive` PUT endpoint * Added `/v1/products/{id}/unarchive` PUT endpoint ## March 6, 2025 * Added `/v1/invoices/{id}/transactions` POST endpoint * Added `/v1/invoices/{id}/transactions/{transactionId}` DELETE endpoint * Added `provider_id` on `/v1/customers/providers-bulk-update` POST endpoint ## February 27, 2025 * Added `Subscription.phases` on `/v2/subscriptions` POST endpoint * Added `Subscription.phases` on `/v2/subscriptions/{id}` GET endpoint ## February 4, 2025 * Added `Invoice.payment_method_id` on `/v1/invoices` POST endpoint * Added `Invoice.line_items[].tax_rate` on `/v1/invoices` POST endpoint ## January 28, 2025 * Added `Invoice.line_items[].product_id` on `/v1/invoices` POST endpoint ## January 15, 2025 * Added `Subscription.quote` on `/v2/subscriptions/{id}` GET endpoint ## January 14, 2025 * Added `/v2/subscriptions/{id}/phases` GET endpoint * Added `/v2/subscriptions/{id}/phases/{phaseId}` GET endpoint * Added `Subscription.current_phase_id` on `/v2/subscriptions` GET endpoint * Added `Subscription.current_phase_id` on `/v2/subscriptions/{id}` GET endpoint ## January 10, 2025 * Added `Quote.original_subscription_id` on `/v1/quotes` GET endpoint * Added `Quote.original_subscription_id` on `/v1/quotes/{id}` GET endpoint ## January 8, 2025 * Added `/v1/invoices/{id}` DELETE endpoint ## November 6, 2024 * Added `/v1/customers/{id}/unarchive` PUT endpoint * Added `/v1/invoices/{id}` PATCH endpoint * Added `/v1/subscriptions/{id}/activate` POST endpoint ## October 23, 2024 * Added `/v1/customers/{id}/payment-methods` GET endpoint * Added `/v1/customers/{id}/payment-methods/{paymentMethodId}` GET, DELETE endpoints ## October 8, 2024 * Added `/v1/companies` POST endpoint ## August 21, 2024 * Added `custom_property.created`, `custom_property.updated`, `custom_property.deleted`, `custom_property.value_created`, `custom_property.value_updated`, `bank_account.created`, `bank_account.deleted` webhooks ## August 20, 2024 * Added `/v1/taxes/rates` GET endpoint * Added `/v1/taxes/rates/{id}` GET endpoint * Added `Product.accounting` on `/v1/products/{id}` GET, POST, PUT endpoints * Added `Invoice.line_items[].tax_rate_id` on `/v1/invoices` GET endpoint * Added `Invoice.line_items[].tax_rate_id` on `/v1/invoices/{id}` GET endpoint * Added `Customer.custom_payment_delay` on `/v1/customers` GET endpoint * Added `Customer.custom_payment_delay` on `/v1/customers/{id}` GET, POST, PUT endpoints ## August 12, 2024 * Added `Subscription.custom_properties` on `/v2/subscriptions` GET, POST endpoints * Added `Subscription.custom_properties` on `/v2/subscriptions/{id}` GET, PUT endpoints ## August 7, 2024 * Added `/v1/quotes/{id}/sign` POST endpoint * Added `/v1/invoices/{id}/void` POST endpoint ## July 30, 2024 * Added `Customer.timezone` on `/v1/customers` GET, POST endpoints * Added `Customer.timezone` on `/v1/customers/{id}` GET, PUT endpoints ## July 3, 2024 * Added `/v1/organisations/{id}` GET endpoint * Added `/v1/organisations/{id}` PATCH endpoint * Added `Customer.organisation_id` and `Customer.organisation_invoicing` on `/v1/customers` POST endpoint * Added `Customer.organisation_id` and `Customer.organisation_invoicing` on `/v1/customers/{id}` GET, PUT endpoints * Added `Subscription.contract_start` and `Subscription.contract_end` on `/v2/subscriptions/*` endpoints * Added `Subscription.products[].attached_at` and `Subscription.products[].detached_at` on `/v2/subscriptions/*` endpoints * Added `/v1/subscriptions/{id}/reinstate` POST endpoint * Added `update_prices` `SubscriptionUpdate.type` on `/v1/subscriptions/{id}/update` POST endpoint * Added `/v1/subscriptions/{id}/update-many` POST endpoint * Major Deprecation warning * Deprecating `Subscription.starts_at` in favor of `Subscription.contract_start` * Major * Removing `SubscriptionUpdate.payload.billing_item_ids` in favor of `SubscriptionUpdate.payload.product_ids` for `add_coupon` update type * Removing `add_item` `SubscriptionUpdate.type` in favor of `add_product` * Removing `remove_item` `SubscriptionUpdate.type` in favor of `remove_product` ## June 26, 2024 * Added `/v1/quotes` POST endpoint * Added `/v1/quotes/{id}/download` GET endpoint * Added `/v1/quotes/{id}/send` POST endpoint * Added `/v1/quotes/{id}/void` POST endpoint ## June 12, 2024 * Added `Customer.custom_properties` on `/v1/customers` GET endpoint ## May 27, 2024 * Added `/v1/quotes` GET endpoint * Added `/v1/quotes/{id}` GET endpoint * Added `/v1/quotes/{quoteId}/files/{id}/download` GET endpoint ## April 2, 2024 * Major Removed deprecated subscription endpoints * Removed `GET /v1/subscriptions` in favor of `GET /v2/subscriptions` * Removed `GET /v1/subscriptions/{id}` in favor of `GET /v2/subscriptions/{id}` * Removed `POST /v1/subscriptions` in favor of `POST /v2/subscriptions` * Removed `GET /v1/billing-plans/{id}` in favor of `GET /v1/plans/{id}` * Removed `GET /v1/billing-scenarios` * Removed `GET /v1/billing-scenarios/{id}` ## March 6, 2024 * Added `/v1/subscriptions/{id}/pause` PUT endpoint * Added `/v1/subscriptions/{id}/reactivate` PUT endpoint * Added `/v1/subscriptions/refresh` POST endpoint ## March 5, 2024 * Added `/v1/webhooks/endpoints` GET, POST endpoints * Added `/v1/webhooks/endpoints/{id}` GET, PUT, DELETE endpoints ## March 1, 2024 * Major Removed unit concept on wallets (only money pocket) in favor of credit-type products to manage credit units. * Removed `WalletBalance.units` * Removed `WalletSettings.unit_credit_prices` * Removed `WalletTransaction.units` and `WalletTransaction.transaction_id` ## February 28, 2024 * Major Removed unique current customer subscription in favor of subscriptions array. * Removed `Customer.current_subscription_id` on `/v1/customers` GET endpoint * Removed `Customer.current_subscription` on `/v1/customers/{id}` GET endpoint ## February 20, 2024 * Added `Customer.type` on `/v1/customers` GET, POST and PUT endpoints * Added `Customer.invoice_emails` on `/v1/customers` GET, POST and PUT endpoints * Added `Customer.vat_rate_custom` on `/v1/customers` GET, POST and PUT endpoints * Added `external` option on `Customer.payment_method_type` on `/v1/customers` POST and PUT endpoints ## February 16, 2024 * Major Planned for April 1, 2024 * Removing `GET /v1/subscriptions` in favor of `GET /v2/subscriptions` * Removing `GET /v1/subscriptions/{id}` in favor of `GET /v2/subscriptions/{id}` * Removing `POST /v1/subscriptions` in favor of `POST /v2/subscriptions` * Major Planned for February 28, 2024 * Removing `Customer.current_subscription_id` on `/v1/customers` GET endpoint in favor of `Customer.subscriptions` * Removing `Customer.current_subscription` on `/v1/customers/{id}` GET endpoint in favor of `Customer.subscriptions` # Chart of accounts Source: https://docs.hyperline.co/docs/accounting/accounts Manage the chart of accounts for each Hyperline ledger: pre-populate GL accounts, customize them, and reference them in accounting rules. Each ledger has a chart of accounts — the list of GL (General Ledger) accounts that Hyperline uses when posting journal entries. Accounts are referenced in your [accounting rules](./rules) to determine which account receives each debit or credit. ## Default account sets When you create a ledger, Hyperline can pre-populate its chart of accounts with a standard set of accounts matching your chosen accounting standard: | Standard | Included accounts | | ---------------- | ------------------------------------------------------------------------ | | IFRS | International template (1000s assets, 4000s revenue, 6000s expenses) | | Local GAAP | International template (same as IFRS) | | US GAAP | ASC 606 revenue accounts with CECL allowance for credit losses (ASC 326) | | UK GAAP | FRS 102 naming (Trade Debtors, Deferred Income, VAT Output) | | FR GAAP | Plan Comptable Général codes (512000, 706100, 706200, etc.) | | Management | M-codes for ARR/MRR bucketing (new, expansion, churn) | | Consolidation | Minimal set for intercompany and adjustment entries | | Audit adjustment | Same as consolidation | You can modify these defaults at any time. Default account sets also come with a matching set of default [accounting rules](./rules) pre-configured for those accounts. ## Account types Hyperline supports the following GL account types: | Type | Description | | ------------------ | --------------------------------------------------------------- | | `Asset` | Cash, accounts receivable, and other resources owned | | `Contra Asset` | Offsets an asset account (e.g. allowance for doubtful accounts) | | `Liability` | Deferred revenue, tax payable, customer credits | | `Contra Liability` | Offsets a liability account | | `Equity` | Retained earnings, share capital | | `Revenue` | Subscription revenue, usage revenue, one-off fees | | `Contra Revenue` | Discounts, refunds, promotional adjustments | | `Expense` | Bad debt, payment processing fees | ## Add an account Go to **Accounting** > **Settings** > **Accounts** and click **Add account**. Each account requires: * **Code** — a unique identifier within the ledger (e.g. `4000`, `706100`) * **Name** — a descriptive label (e.g. "Subscription Revenue") * **Type** — one of the account types listed above ## Edit an account Click the edit icon next to any account in the accounts list. You can update the code, name, and type at any time. ## Delete an account Click the delete icon next to the account and confirm. Accounts with existing journal entry lines cannot be deleted. ## Sync accounts from your accounting provider An existing chart of accounts can be pulled directly from the provider instead of creating accounts manually. The **Sync accounts** button only appears once you have connected an accounting integration. Go to **Settings** > **Integrations** to connect your provider first. Go to **Accounting** > **Settings** > **Accounts** and click **Sync accounts**. Hyperline will fetch the current chart of accounts from the provider and import the accounts into your ledger. [Supported providers](/integrations/overview#accounting-software) for account sync are Xero, QuickBooks, Exact Online, Pennylane, NetSuite, and Rillet. You can then reference these accounts in your rules and map them to Hyperline's standard account roles (accounts receivable, revenue, deferred revenue, etc.). Syncing accounts from your provider ensures that account codes match exactly — which is required for journal entries to post correctly in your external accounting software. ## Browse account activity The chart of accounts view (**Accounting** > **Ledger**) lets you filter accounts by **type** and by **quarter**. Each row shows the period balance for the selected quarter. Click **View journal entries** on any account to drill into its [journal entries](./entries) for that period. ## Export financial reports From the chart of accounts view, the **Export** dropdown produces three reports scoped to the currently selected quarter: | Report | Scope | Format | | -------------------- | ------------------------------------------------------------------------------------ | ------ | | **General ledger** | All entries posted between the start and end of the selected quarter | XLSX | | **Income statement** | Revenue and expenses for the selected quarter, in the ledger's functional currency | XLSX | | **Balance sheet** | All asset, liability, and equity balances as of the last day of the selected quarter | XLSX | Exports run asynchronously. You will be notified in-app once the file is ready, and it will be available from **Exports** in the main navigation. # Journal entries Source: https://docs.hyperline.co/docs/accounting/entries Explore journal entries by GL account and quarter, drill into invoice-level entries, and audit accounting activity from any Hyperline ledger. The journal entries view lets you explore all activity for a specific GL account within a selected quarter. You can access it from two places: * The accounts list in a ledger — click **View journal entries** on any account * The accounting section of an [invoice](/docs/invoices/invoice-page) detail page — click **View in ledger** on any of the invoice's journal entries Journal entries view The view opens as a side panel with two panels: * **Left** — a paginated list of journal entry lines for the selected account and quarter, with filters * **Right** — the full details of the selected entry ## Left panel — entry lines The header shows the account and quarter context: `[Code] - [Account Name] / Journal entries / Q[N] YYYY`. Each row in the list represents a single journal entry line and shows: | Column | Description | | ----------------- | --------------------------------------------------------------------------- | | **Journal entry** | Entry number (e.g. `JE-001`) | | **Entry date** | Date of the journal entry | | **Status** | `Posted` (green) or `Draft` (gray); posted entries include the posting date | | **Rule** | Code of the accounting rule that generated the line | | **Debit** | Amount if the line is a debit; `—` otherwise | | **Credit** | Amount if the line is a credit; `—` otherwise | ### Filters Use the filters dropdown to narrow results: * **Type** — filter by `Debit` or `Credit` lines * **Date range** — filter by entry date (`date__gte` / `date__lte`) * **Search** — search by invoice number, customer, or amount ## Right panel — entry details Click any line in the left panel to open its full journal entry on the right. The panel shows: * **Entry number** and status (with posting date if posted) * **Total debit** and **total credit** for the entry * Related entities: customer, subscription, invoice (when applicable) * Exchange rate and exchange rate date (shown only when rate ≠ 1) ### Entry lines spreadsheet All debit and credit lines of the entry are displayed in a compact spreadsheet: | Column | Description | | ----------- | ------------------------------ | | **Rule** | Accounting rule code | | **Account** | GL account code and name | | **Debit** | Amount if the line is a debit | | **Credit** | Amount if the line is a credit | When an entry has lines across multiple products, lines are grouped by account with each product shown as a sub-row. The line corresponding to the one selected in the left panel is highlighted. ## Export Click **Export** at the top of the journal entries view to download a **general ledger** XLSX. The export respects the filters currently applied — account, status (`posted` / `draft`), and the selected quarter — so you can scope it to a single account, a specific posting state, or a full quarter. Is something still unclear? Don't hesitate to reach out to our team via the in-app chat if you need additional support. # Ledgers Source: https://docs.hyperline.co/docs/accounting/ledgers Create and manage Hyperline accounting ledgers per invoicing entity for statutory, management, or consolidation books with isolated entries. A ledger is a set of books attached to one of your [invoicing entities](/docs/getting-started/invoicing-entities). All [journal entries](./entries), [accounts](./accounts), and [accounting rules](./rules) are scoped to a ledger. You can create multiple ledgers per invoicing entity to maintain separate books for different purposes — statutory reporting, management accounts, consolidation adjustments, and so on. ## Create a ledger To create a ledger, go to **Accounting** and click **Create ledger**. You will be asked to configure: * **Name** — a label to identify the ledger (e.g. "Statutory – IFRS", "Management") * **Invoicing entity** — the entity this ledger is attached to * **Currency** — the functional currency for this ledger; amounts in other currencies are converted using the exchange rate at invoice time * **Journal entry pattern** — the numbering format for journal entries (e.g. `JE-{YYYY}-{number}`) * **Ledger type** — the starting chart of accounts and configuration to apply (see ledger types below) If you plan to sync this ledger with an external accounting provider, select the account standard that matches your provider's chart of accounts — this simplifies the account mapping later. ## Ledger types Hyperline supports the following ledger types, each pre-configured with a matching chart of accounts: | Type | Purpose | Default account set | | ------------------ | ---------------------------------------- | ------------------------------------------------------------------------ | | `IFRS` | International statutory reporting | International template (1000s assets, 4000s revenue, 6000s expenses) | | `US_GAAP` | US statutory reporting | ASC 606 revenue accounts with CECL allowance for credit losses (ASC 326) | | `UK_GAAP` | UK statutory reporting | FRS 102 naming (Trade Debtors, Deferred Income, VAT Output) | | `FR_GAAP` | French statutory reporting | Plan Comptable Général codes | | `LOCAL_GAAP` | Other local statutory reporting | International template (same as IFRS) | | `MANAGEMENT` | Internal reporting, ARR/MRR tracking | M-codes for ARR/MRR bucketing (new, expansion, churn) | | `CONSOLIDATION` | Group-level eliminations and adjustments | Minimal intercompany and adjustment accounts | | `AUDIT_ADJUSTMENT` | Post-close corrections | Same as consolidation | Each ledger maintains its own chart of accounts, rules, and journal entry sequence independently. ## Edit a ledger To update a ledger's name or entry pattern, go to **Accounting** > **Settings** and click **Edit ledger**. ## Delete a ledger Ledgers can be deleted from **Accounting** > **Settings**. Deleting a ledger permanently removes its accounts, rules, and journal entries. Deleting a ledger is irreversible. Make sure you no longer need the ledger's history before proceeding. # Accounting overview Source: https://docs.hyperline.co/docs/accounting/overview Automate general ledger entries, revenue recognition, and accounting rules from your Hyperline billing activity, with no manual bookkeeping. Hyperline's accounting module automates the production of journal entries from your billing activity. When an invoice is issued, a payment is settled, or a credit note is created, Hyperline applies your accounting rules to generate the corresponding general ledger entries — removing manual bookkeeping and ensuring your books stay in sync with your revenue. The accounting module is currently in **beta**. To get access, reach out to the team via the in-app chat or [contact sales](https://www.hyperline.co/talk-to-sales). ## Core concepts The accounting module is built around five interconnected concepts: **Ledger (GL — General Ledger)** A ledger represents one set of books attached to an invoicing entity. You can maintain multiple ledgers per invoicing entity — for example, a statutory ledger (IFRS, US GAAP) alongside a management ledger for internal reporting. **Chart of accounts** Each ledger has its own chart of accounts — the list of GL accounts used in journal entries (accounts receivable, revenue, deferred revenue, tax payable, etc.). Hyperline provides standard account sets for common accounting standards and allows you to define your own. **Accounting rules** Rules define which GL accounts to debit and credit for a given billing event. They are organised by category (invoice issued, invoice settled, credit note created, revenue recognition) and can be scoped to specific products, customers, currencies, or payment methods using filters. When multiple rules match, Hyperline applies them in priority order — the rule with the highest priority wins. **Journal entries** Journal entries are generated automatically when billing events occur, based on your rules. Each entry contains one or more debit/credit lines linked to the corresponding invoice, customer, and subscription. Once posted, entries cannot be deleted — corrections are made via reversal entries. **Revenue recognition** For products where revenue must be deferred and recognised over time, Hyperline manages recognition schedules automatically. Each line item on an invoice can have its own recognition method, spread across the service period according to your rules. ## How they work together When a billing event occurs (e.g. an invoice is issued), Hyperline: 1. Evaluates the applicable accounting rules for that event 2. Determines the correct GL accounts based on the product, customer, currency, and other filters 3. Posts a journal entry with the debit and credit lines 4. If the rule includes revenue recognition, creates a recognition schedule to spread revenue over the service period ## Navigating to accounting The **Accounting** section is accessible from the main navigation. From there, select the ledger you want to work with using the ledger selector at the top of the page. Within a ledger, you will find: * **Ledger** — the chart of accounts, with per-quarter balances and exports (general ledger, income statement, balance sheet) * **Journal entries** — browse posted entries by account, with export to XLSX * **Revenue recognition** — explore recognition schedules and the revenue waterfall, with XLSX export * **Settings** — manage your accounts, rules, and ledger configuration You can also reach the entries and recognition schedules for a single invoice directly from that invoice's detail page (**Accounting** section), which deep-links into the ledger view. Reach out via the in-app chat for support. # Revenue recognition Source: https://docs.hyperline.co/docs/accounting/revenue-recognition Automate deferred revenue and recognition schedules in Hyperline, with per-line schedules and journal entries posted as revenue is earned. When a customer pays upfront for a service delivered over time, the revenue cannot be recognised immediately — it must be deferred and released as the service is performed. Hyperline manages this automatically by creating recognition schedules on each invoice line item and posting the corresponding journal entries as revenue is earned. All revenue recognition amounts are **net of tax**. Tax is always posted separately as a liability (output tax account) at the time the invoice is issued, regardless of the recognition method applied to the revenue. ## Recognition methods The recognition method is defined in your **Revenue recognition** accounting rule. It can be set at the rule level and overridden for specific products or customer segments using filters. ### Over time Revenue is spread evenly across the service period using a straight-line allocation. You configure the **granularity** at which Hyperline posts recognition entries: | Granularity | How revenue is spread | | ----------- | -------------------------------------------- | | Daily | Recognised each day over the service period | | Monthly | Recognised at the end of each calendar month | | Quarterly | Recognised at the end of each quarter | | Yearly | Recognised at the end of each year | A customer pays €12,000 upfront for a 12-month SaaS subscription starting 1 January. With monthly granularity, Hyperline defers the full €12,000 at invoice time and recognises €1,000 each month from January to December. ### Point in time All revenue is recognised at a single date. You configure the **recognition date basis**: | Basis | Recognition date | | ------------------ | ----------------------------------- | | Invoice date | The date the invoice was issued | | Service start date | The first day of the service period | | Service end date | The last day of the service period | A one-off implementation fee with "service end date" basis will remain deferred until the end of the project, at which point the full amount is recognised. ### Usage-based Revenue is recognised in line with what your customers actually consume. Use this method for **metered products** and **credit packs** — the amount you recognise each day reflects that day's usage, not a flat allocation. When the invoice is issued, the full amount is parked in deferred revenue. Each day, Hyperline releases the share corresponding to that day's consumption. Days with no usage recognise nothing; busy days recognise more. #### Recognition timing A daily job sweeps every day's slice and only releases revenue once the day's usage total has been seen unchanged on two consecutive runs — i.e. no late events landed between observations. This stability gate gives a **≥24 hour grace period** for late-arriving usage events. In practice, day **D**'s revenue is recognised at the next-but-one daily run (typically two days after the consumption day). A day with zero observed usage gets an additional grace window before being closed at zero, so a slow-starting customer or a delayed ingestion pipeline doesn't permanently zero out an early slice. Once a day's revenue has been recognised, **events landing for that day after recognition are not retroactively allocated**. If your usage pipeline regularly produces late events older than 48 hours, reach out before relying on usage-based recognition for material amounts. | Setting required | Where to set it | | ------------------------------ | ------------------------ | | A revenue account | Revenue recognition rule | | A deferred revenue account | Revenue recognition rule | | Metered or credit-pack product | Catalog | A customer is invoiced €600 upfront for a metered product over a 30-day service period and consumes 1,000 units across that period. Hyperline defers €600 at invoice time, then recognises each day in proportion to that day's consumption — a day with 50 units recognises €30, a day with no usage recognises nothing. #### Credit packs Credit packs follow the same usage-based engine, with the schedule anchored on the **credit topup** rather than a metered aggregator: * The service window is the topup's **validity period** (`createdAt → expiresAt`). Non-expiring topups inherit the line item's billing period. * Each day, Hyperline reads the credits **drawn down** that day and releases the proportional share of the topup's value. * When a customer holds **multiple active topups**, drawdown is attributed **FIFO** — the oldest topup is consumed first, so its schedule recognises ahead of newer ones. A customer buys a €1,000 / 500-credit pack valid for 90 days. Over that window they consume 400 credits. Hyperline recognises €800 across the 90 days in proportion to daily consumption; the remaining €200 stays deferred until expiry. ##### Breakage on expiry When a topup expires with credits unconsumed, the unrecognised remainder is recognised in a single entry on the expiry date as **breakage** (per ASC 606-340-10). Any pending future slices on the schedule are cancelled, and the schedule is closed. Continuing the example above: on day 90, the topup expires with 100 credits unused. Hyperline posts a single recognition entry for the remaining €200 on the expiry date and marks the schedule completed. Flat fees and seats use over-time or point-in-time recognition — usage-based doesn't apply to non-metered, non-credit products. ## Discount recognition When a line item includes a discount, you control how the discount amount is treated at recognition time using the discount recognition mode in the **Invoice posted** rule: | Mode | Behaviour | | -------------- | ---------------------------------------------------------------------------------------------- | | Immediate | Discount is recognised in full at invoice time (posted as contra-revenue immediately) | | Deferred | Discount follows the same recognition schedule as the revenue (spread over the service period) | | Use net amount | Revenue is recognised net of the discount — no separate discount entry is created | ## Recognition schedule statuses Each invoice line item gets a recognition schedule. The schedule can have the following statuses: | Status | Meaning | | ------------- | ------------------------------------------------------------- | | `pending` | The schedule has been created but recognition has not started | | `in_progress` | Recognition has started; some entries have been posted | | `completed` | The schedule is fully processed and closed | | `cancelled` | The schedule was cancelled before recognition began | ## Exploring recognition schedules Go to **Accounting** > **Revenue recognition** to browse all recognition schedules for a ledger. You can filter by customer, product, subscription, or date range. Each schedule shows: * The total amount to be recognised (net of tax) * The amount already recognised * The remaining deferred balance * The individual recognition entries (slices) with their dates and amounts ## Revenue waterfall The revenue waterfall is a matrix that shows, for each **booking cohort** (the month invoices were issued), how the booked revenue unwinds into recognised revenue across subsequent periods — and how much is still deferred. The matrix has three sections: | Section | What it shows | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Booked revenue** | One row per booking cohort; the **Total** column is the gross amount invoiced (net of tax) in that period | | **Recognised revenue** | One column per recognition period; each cell is the amount from that cohort recognised in that month | | **Total revenue** | **Recognised** = cumulative sum of all recognition entries posted so far; **Remaining** = Booked − Recognised = the deferred revenue balance still on the balance sheet | All waterfall amounts are net of tax and expressed in the ledger's functional currency. ## Export Click **Export** on the revenue recognition view to download the waterfall as XLSX. The export covers the booked cohorts for the selected year and includes per-invoice-line-item breakdowns so you can reconcile recognition entries against the underlying invoice lines. # Accounting rules Source: https://docs.hyperline.co/docs/accounting/rules Configure accounting rules that determine which GL accounts Hyperline debits and credits for invoices, payments, credit notes, and refunds. Accounting rules define which General Ledger (GL) accounts Hyperline uses when posting journal entries. Each rule belongs to a category that matches a specific billing event, and can be scoped to a subset of products, customers, currencies, or payment methods using filters. ## Rule categories | Category | Trigger | What it controls | | ----------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | | **Invoice posted** | An invoice is finalised and emitted | Accounts receivable, revenue (or deferred revenue), output tax, discounts | | **Invoice settled** | A payment transaction is settled | Cash or bank account, payment clearing, any payment processing fees | | **Credit note created** | A credit note is issued | Customer credit liability, contra-revenue entries | | **Revenue recognition** | No independent trigger — applied at invoice posting time alongside the Invoice posted rule | Recognition method, schedule granularity, discount recognition mode | Rules of all four categories can coexist in the same ledger. Revenue recognition settings are resolved at invoice posting time alongside the **Invoice posted** rule — they are not triggered by a separate event. ## Account mappings Each rule specifies which GL account to use for each role in the journal entry. The available account roles depend on the rule category: **Invoice posted** * Accounts receivable * Revenue account * Deferred revenue * Output tax / VAT * Discount account * Deferred discount account * Contra-revenue account * Customer credits account * Bad debt / allowance for doubtful accounts **Invoice settled** * Cash / bank account * Payment clearing account * Provider fees expense account * Payment processing fees account * Accounts receivable (cleared on settlement) **Credit note created** * Customer credits account * Contra-revenue account * Deferred discount account * Revenue account (reversed) * Output tax account (reversed) * Accounts receivable (for unpaid invoices) **Revenue recognition** * Revenue account (when recognised) * Deferred revenue (until recognised) ## View the rule tree **Accounting** > **Settings** > **Rules** displays all rules grouped by category, showing which rules would apply and in what order for each event type. This is useful for auditing your rule configuration before going live. ## Filters Rules can be scoped using one or more filters. Available filters depend on the rule category. When a billing event occurs, Hyperline evaluates all matching rules and applies them in priority order. **Invoice posted** | Filter | Description | | ---------------- | ----------------------------------------------------------------------------------- | | Products | Match specific products by ID | | Product types | Match by product type (`flat_fee`, `dynamic`, `addon`, `seat`, `one_off`, `credit`) | | Coupons | Match invoices where a specific coupon was applied | | Currencies | Match invoices in a given currency | | Countries | Match customers billed from a given country | | Billing interval | Match by billing period (e.g. monthly, quarterly, annual, one-off) | **Invoice settled** | Filter | Description | | ----------------- | ------------------------------------------------------------------------------ | | Payment providers | Match by payment provider (Stripe, GoCardless, etc.) | | Payment methods | Match by method type (card, SEPA direct debit, ACH, BACS, bank transfer, etc.) | | Currencies | Match transactions in a given currency | **Credit note created** | Filter | Description | | ------------- | ----------------------------------------------------------------------------------- | | Product types | Match by product type (`flat_fee`, `dynamic`, `addon`, `seat`, `one_off`, `credit`) | | Currencies | Match credit notes in a given currency | | Countries | Match customers billed from a given country | **Revenue recognition** | Filter | Description | | ---------------- | ----------------------------------------------------------------------------------- | | Products | Match specific products by ID | | Product types | Match by product type (`flat_fee`, `dynamic`, `addon`, `seat`, `one_off`, `credit`) | | Coupons | Match invoices where a specific coupon was applied | | Currencies | Match invoices in a given currency | | Countries | Match customers billed from a given country | | Billing interval | Match by billing period (e.g. monthly, quarterly, annual, one-off) | An empty filter matches everything — rules with no filters act as catch-all defaults. ## Priority and fallback When multiple rules match the same billing event, Hyperline applies them using a **priority overlay**: 1. All matching rules are collected and sorted by priority (ascending) 2. Rules are applied in order — each rule overrides only the account roles it explicitly defines 3. The rule with the **highest priority number wins** for any given account role This means you can define a low-priority default rule that covers all products, then add higher-priority rules to override specific account mappings for individual products or customer segments. You have a default invoice issued rule (priority 10) that maps all revenue to account `4000 – Revenue`. You then add a second rule (priority 50) scoped to a specific product that maps its revenue to `4100 – Usage Revenue`. When an invoice is issued for that product, Hyperline uses `4100` for that product's line items and `4000` for everything else. ### Tiebreaker at equal priority When two matching rules share the same priority, Hyperline picks the **more specific** one: 1. A rule scoped to **customers** wins over a rule scoped to products 2. A rule scoped to **products** wins over a rule with no customer or product filter 3. If both rules are equally specific, the rule created first wins Only **customer** and **product** filters affect this tiebreaker. Other filters (coupons, currencies, countries, intervals, payment methods) do not — use distinct priorities to disambiguate them. Two rules both have priority 10: * Rule A scoped to customer `cust_123` * Rule B scoped to product `prod_456` For an invoice line where both rules match, Rule A wins because customer-scoped rules take precedence over product-scoped rules at the same priority. ## Add a rule Go to **Accounting** > **Settings** > **Rules** and click **Add rule**. 1. Select the rule **category** 2. Assign a **priority** (integer; higher wins) 3. Configure the **account mappings** for each role 4. Optionally add **filters** to scope the rule ## Edit and delete rules Click the edit or delete icon next to any rule in the rule list. Deleting a rule does not affect already-posted journal entries. # Automated exports Source: https://docs.hyperline.co/docs/analytics/automated-exports Set up automated data syncs that push Hyperline datasets — invoices, customers, subscriptions — to your PostgreSQL database on a recurring schedule. Automated exports let you keep selected Hyperline datasets available in your own database for analysis, reporting, and finance operations. Instead of downloading CSV files manually, you can create a **Data sync** that writes Hyperline data to a destination database on a recurring schedule. Each selected dataset is written to its own table. In-app setup currently supports PostgreSQL destinations. Use a dedicated database, schema, or write user for Hyperline exports whenever possible. ## Before you start To create a data sync, make sure that: * You have access to **Settings** in Hyperline * Your destination PostgreSQL database can receive connections from Hyperline * The database user can create tables and write rows * The connection URL is available If your database requires IP allowlisting, allow traffic from: * `15.188.105.163` * `15.188.215.105` * `35.181.129.14` You can also connect through an SSH tunnel when creating the PostgreSQL connection. ## Create a data sync 1. Go to **Settings** > **Data syncs** 2. Click **New sync** 3. Select an existing PostgreSQL connection, or choose **Create new connection** 4. Enter the connection name and database connection details 5. Select the sync status: * **Active**: run automatically on the configured schedule * **Paused**: keep the configuration without scheduled runs 6. Select the sync frequency: * **Every 12 hours** * **Every 24 hours** 7. Select the data to sync 8. Click **Save changes** Hyperline validates the database connection before saving it. After the sync is created, it appears in the **Data syncs** list with its status, selected table count, frequency, and last sync date. ## Available data You can sync invoice exports and Hyperline reports. | Data | Destination table | | -------------------------- | --------------------------------------------- | | Invoices | `hyperline_invoices` | | Invoice line items | `hyperline_invoice_line_items` | | Aged balances | `hyperline_report_aged_balances` | | All customers | `hyperline_report_all_customers` | | All subscriptions | `hyperline_report_all_subscriptions` | | Detailed revenue | `hyperline_report_detailed_revenue` | | Draft invoices | `hyperline_report_draft_invoices` | | Line by line revenue | `hyperline_report_line_by_line_revenue` | | Live subscriptions | `hyperline_report_live_subscriptions` | | Open invoices | `hyperline_report_open_invoices` | | Outstanding invoices | `hyperline_report_outstanding_invoices` | | Renewals | `hyperline_report_renewals` | | Revenue per country | `hyperline_report_revenue_per_country` | | Revenue per line item name | `hyperline_report_revenue_per_line_item_name` | | Revenue per plan | `hyperline_report_revenue_per_plan` | | Revenue per product | `hyperline_report_revenue_per_product` | For more context on the report definitions, see [Reports](./reports). ## How syncs write data Each selected dataset is refreshed as a snapshot. Hyperline creates the destination table if it does not exist, then replaces the table content during each successful sync. If the table already exists, its schema must be compatible with the expected Hyperline columns. Extra columns can exist, but required columns must be present with compatible types. Every exported table includes Hyperline metadata columns, such as: | Column | Description | | -------------------------------- | ------------------------------------------------ | | `_hyperline_source_id` | Stable row identifier used by the sync | | `_hyperline_synced_at` | Time when the row was written to the destination | | `_hyperline_sync_run_id` | Identifier of the sync run that wrote the row | | `_hyperline_report_generated_at` | Time when the report snapshot was generated | | `_hyperline_report_template` | Source report template | | `_hyperline_row_index` | Row position in the generated report | | `_hyperline_row_hash` | Hash of the source row content | Keep Hyperline-managed tables separate from your own transformed tables. Build downstream models or BI views from the `hyperline_*` tables instead of editing the synced tables directly. ## Run and monitor syncs Scheduled syncs run only when the sync is **Active**. You can also click **Run now** from the sync list or sync detail page to start a manual run. Open a sync to review **Run history**. Each run shows: * Whether it was manual or scheduled * Status: `pending`, `processing`, `done`, `partial`, or `error` * Start time * Number of selected tables * Rows written * Error message, when available If a run fails, check that the destination database is reachable and that the user still has permission to create tables and write rows. ## Delete a data sync Deleting a data sync stops future runs. Run history is kept for auditability, but Hyperline no longer updates the destination tables for that sync. ## Related pages * [Reports](./reports) * [Invoice exports](../invoices/exports) * [Pull usage data with connectors](../usage/usage-data-with-connectors) # Dashboard Source: https://docs.hyperline.co/docs/analytics/dashboard Explore the Hyperline dashboard: track collected revenue, outstanding invoices, and weekly performance with daily refreshed billing metrics. The dashboard is the first interface you see when logging in to your Hyperline account. It gives you a quick, effective overview of your business and hints on actions you can take to recover money faster. It displays the amount collected this week along with the number of invoices involved. The data displayed on the dashboard is updated every day at midnight UTC. You need to have the proper permission to access the dashboard. ## Business metrics This section provides key financial insights at a glance, helping you monitor revenue performance, debt, and cash flow. This information can be filtered by currency, invoicing entity, and date range. ### ARR Annual Recurring Revenue (ARR) represents the total annualized revenue a SaaS company expects to generate from active subscriptions over a year. It provides a long-term view of predictable revenue and helps track revenue growth trends. In Hyperline, ARR is a live metric based on the **current subscriptions' configurations and their consumption**. Past or future phases and subscriptions are not taken into account — it reflects a snapshot of the current value as of today, which means it can fluctuate over time. Calculation details: * Coupons with a `once` application are excluded. * Coupons with a `forever` application are included. * Coupons with a duration shorter than the subscription period are excluded. * Taxes (e.g., VAT) are excluded. The number of customers reflects the total active subscribers contributing to ARR, while ARPA (Average Revenue Per Account) represents the average revenue per customer, calculated as ARR ÷ number of customers. ### Outstanding debt Outstanding debt represents the total amount of unpaid invoices, helping businesses track overdue and pending revenue. It is categorized into three components: * Pending: Invoices that are issued but still within the payment term. * Late: Invoices that are past their due date. * Error: Invoices where payment methods could not be charged after retries. Monitoring outstanding debt allows businesses to stay on top of collections, reduce late payments, and address potential billing issues. ### Cash flow This metric tracks the total revenue collected month over month, providing visibility into financial inflows. It helps assess liquidity, revenue trends, and payment patterns. * Recurring revenue: Revenue collected from subscriptions, representing predictable, ongoing revenue. * One-off revenue: Revenue collected from one-time payments and manual invoices. ### Additional metrics These metrics provide insights into upcoming renewals, pending deals, tax collections, and billing issues. For each of these metrics, you can explore the detailed elements by clicking on the `eye` button. * **Contracts renewing soon** represent the contracts attached to subscriptions automatically renewing in the next 30 days. * **Quotes pending signature** indicate potential revenue that has yet to be confirmed. * **Taxes collected** represent the total amount of tax collected from invoices, providing visibility into tax obligations. * **Errored invoices** highlight invoices that failed due to payment errors, indicating potential revenue at risk that may require action. ## Billing insights Tracking unpaid balances helps businesses prioritize revenue collection, while renewal monitoring ensures revenue continuity. Together, these insights improve cash flow stability and financial management. ### Top 5 balances due This section highlights the five customers with the highest outstanding debt, allowing you to quickly identify and follow up on overdue payments. For each customer, it displays the total unpaid balance and the number of invoices involved. ### Contracts renewing soon This section highlights upcoming subscription renewals, helping businesses anticipate revenue retention and manage customer relationships proactively. For each contract, it displays the customer name, the contract value, whether it renews automatically, and the renewal date. # Insights Source: https://docs.hyperline.co/docs/analytics/insights Track MRR, ARR, churn, and revenue metrics in Hyperline Insights with interactive charts, drill-down tables, and custom filters for finance teams. The Insights module provides a comprehensive overview of your financial and revenue metrics through interactive charts, detailed tables, and customizable filters. ### Interactive features The Insights module includes several interactive capabilities: * **Clickable charts and tables**: Double-click on any chart bar or table cell to view the underlying data (invoices, transactions, subscriptions) * **Drag to filter date ranges**: Click and drag across chart bars to filter data to a specific time period * **Table cell selection**: Select multiple cells in financial tables to view aggregated statistics (sum, average, min, max) * **Copy data**: Select cells and copy formatted data to your clipboard for use in spreadsheets or reports This feature is in beta and may incur additional charges. Please contact our support team if you're interested. ## Financial page The Financial page gives you a clear view of your financial health. It displays your cash flow, MRR and debt evolution, aged balances, and revenue breakdown. You can filter the data by invoicing entity, currency, and date range. Use the date range picker to select preset periods (**This month**, **Last month**, **This year**, **Last year**, **Last 3 months**, **Last 6 months**, **Last 12 months**, or **All time**), or choose a custom date range. ### Aged balances The **Aged balances** section shows how long invoices have been outstanding, organized by age buckets (1-30 days, 31-60 days, 61-90 days, and 90+ days). The heatmap visualization provides a day-by-day view of outstanding balances, making it easy to identify payment patterns and potential collection issues. Click on any day in the heatmap or any age bucket in the breakdown to view the specific invoices that make up that balance. ### Accounts receivable The **Accounts receivable** section provides a complete breakdown of your outstanding balances. Accounts receivable figures are based on when invoices are sent and their current status, while cash figures reflect when payments are actually received. ### Aged balances The **Aged balances** section includes a heatmap visualization that shows overdue invoices by the number of days past due. Each cell in the heatmap represents a specific day and displays the total outstanding amount for invoices overdue by that many days. Click on any cell to drill down into the invoice-level details for that specific day range. The heatmap supports filtering by: * **As of date**: Calculate balances as of a historical date to see how your aged balances looked at any point in time * **Invoicing entity**: Filter by specific invoicing entities * **Currency**: View amounts in original currency or reporting currency * **Invoice status**: Filter by invoice status (to pay, paid, etc.) Aged balances show what's outstanding at a specific moment in time, so the only time input that affects the heatmap and its drilldown is **As of date**. The `1-30 days` bucket excludes invoices that are still within their payment terms: a recent unpaid invoice whose due date has not yet passed is not counted in that bucket. ### MRR financials The **MRR financials** section offers a detailed breakdown of your Monthly Recurring Revenue. Billed MRR is derived from invoice line items based on the service period start date and billing interval, normalized to monthly amounts. Expansion and contraction reflect contract changes, while new and lost represent contracts that started or ended. Variable revenue includes usage-based charges or credits, as well as committed revenue. #### How MRR is computed * **Proration and partial cycles**: charges that cover only part of a billing cycle (mid-cycle upgrades, cancellations, partial first months) contribute a prorated share of MRR based on how much of the cycle they cover. An 8-day charge on a monthly plan adds roughly 8/30 of a month's MRR, not a full month. * **Credits and refunds**: credit notes and negative lines within an invoice (for example, a prorata refund issued alongside an upgrade) are subtracted from MRR. #### FX rate methodology For customers billed in a currency different from your reporting currency, MRR is normalized using the customer's **most recent invoice's conversion rate**, applied uniformly across their entire MRR history. This approach is aligned with market practices for SaaS analytics. **Why a single rate per customer?** Each invoice captures the FX rate that applied when it was issued. For accounting, that is the correct rate to use — it reflects what was booked at the time. For recurring revenue analysis, using a different rate each month introduces noise: the same £10,000/month customer can appear to expand or contract as GBP/EUR moves, even though nothing about their subscription changed. Anchoring each customer's MRR history to a single conversion rate removes that noise. **Things to keep in mind:** * Historical MRR values are recomputed each time the dashboard is loaded. As conversion rates move, the same past month can show slightly different values between views. Each view is internally consistent, just anchored to a different current rate. * For foreign-currency customers, MRR figures in Insights will not match the amounts in your accounting export line-for-line. This is intentional: the accounting export reflects historical bookings in your accounting currency, while Insights normalizes FX to give a stable business-trend signal. ## Revenue page The Revenue page provides in-depth insights into your revenue streams, including revenue by geography, recurring revenue evolution, and the breakdown between committed and variable components. You can filter the data by invoicing entity, currency, date range, customers, and products. Use the date range picker to select preset periods (**This month**, **Last month**, **This year**, **Last year**, **Last 3 months**, **Last 6 months**, **Last 12 months**, or **All time**), or choose a custom date range. Use the **Clear filters** button to reset customer and product filters. ### Product & customer breakdown The **Revenue per product** section provides a detailed breakdown of your revenue by product and customer. Use this section to track the performance of each product and monitor revenue evolution over time per customer. The revenue table supports infinite scrolling for large datasets and includes: * **Interactive selection**: Select multiple cells to view aggregated statistics * **Sparkline charts**: Each row displays a mini chart showing revenue trends over time * **Invoice drilldown**: Double-click any cell to view the invoices that contributed to that revenue # Reports Source: https://docs.hyperline.co/docs/analytics/reports Browse Hyperline's pre-built finance reports — accounts receivable, MRR movements, cohorts, exports — and download them for deeper analysis. Hyperline provides a comprehensive suite of pre-built reports that give you a clear view of your company's performance. Explore a wide range of analytics designed to empower finance teams in making informed decisions, or export the data for deeper analysis in your preferred external tools. Reports are accessible from the dedicated **Reports** page within the Hyperline platform. ## Available reports Hyperline offers a curated selection of reports essential for assessing various aspects of your company's financial health. Many reports can be viewed directly in the platform with interactive filtering, and all reports are downloadable as CSV files, giving you convenient access to the data you need at any time. These reports can also be exported using the [exports API](../../api-reference/endpoints/exports/create-export). ## Preview reports Many reports can be viewed directly in Hyperline with interactive filtering and pagination. Click the **View** button next to a report to explore the data in a table format with infinite scroll for large datasets. ### Available viewable reports The following reports support in-app viewing: * **Aged Balances**: View outstanding invoices grouped by age * **Revenue per Product**: Analyze revenue breakdown by product * **Revenue per Country**: View revenue distribution by country * **Outstanding Invoices**: See all unpaid invoices * **All Customers**: Browse your complete customer list * **All Subscriptions**: View all active and past subscriptions * **Detailed Revenue**: Explore granular revenue data * **Revenue per Line Item**: Analyze revenue by line item * **Revenue per Plan**: View revenue breakdown by subscription plan * **Line by Line Revenue**: Detailed line-level revenue analysis * **Draft Invoices**: Review invoices in draft status * **Open Invoices**: View all open invoices * **Live Subscriptions**: See currently active subscriptions ### Filtering reports When viewing a report, you can apply filters to narrow down the data: * **Date range**: Select a specific time period to analyze (with quick presets for this month, last month, last 3/6/12 months, this year, last year, or all time) * **Invoicing entity**: Filter by specific invoicing entities (for aged balances) * **Currency**: Filter by specific currencies * **Age bucket**: Filter aged balances by age ranges (1-30, 31-60, 61-90, 90+ days) * **Customers**: Filter by specific customers (for revenue reports) * **Products**: Filter by specific products (for revenue reports) Applied filters are automatically included when you download the report as a CSV file. ## Downloading reports To download a report as a CSV file: 1. Navigate to the **Reports** page or open a report in view mode 2. Click the **Download** or **Download CSV** button 3. Review the export confirmation modal showing: * Report name * Date range (period) * Total row count 4. Click **Download** to generate the CSV file When downloading from the report view page, any active filters (customers, products, currencies, age buckets, invoicing entities, etc.) are automatically applied to the export. Reports with more than 10,000 rows cannot be exported as CSV. Please narrow your date range or apply filters to reduce the number of rows. # Coupons Source: https://docs.hyperline.co/docs/coupons/overview Create reusable coupons in Hyperline that apply fixed-amount or percentage discounts to subscriptions, invoices, and checkout flows. Coupons define the discount that can be applied to a customer. In Hyperline, a coupon can reduce a charge by a fixed amount or by a percentage, and can be reused across subscriptions when the same commercial offer applies to several customers. A coupon is the discount rule. A [promotion code](./promotion-codes) is a customer-facing code that lets customers redeem that coupon on a checkout page. ## When to use coupons Use coupons when you need to apply a recurring or one-time discount to a subscription, quote, or invoice. Common examples include onboarding discounts, partner discounts, contract-specific concessions, and limited-time commercial offers. Coupons are managed from the catalog so they can be created once, tracked centrally, and applied consistently by your team. To offer free or discounted prepaid credits instead of a subscription discount, use [credits](../credits/overview) or [wallet top-ups](../wallets/balance). ## Coupon configuration Each coupon contains three types of settings: | Setting | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **Information** | Name and internal description. The name can appear on customer-facing documents, while the description is for internal context. | | **Discount** | Fixed amount or percentage discount. Fixed amount coupons use one currency. Percentage coupons apply a percentage discount to eligible products. | | **Settings** | Optional redemption deadline, redemption limit, and eligible products. These settings control where and how often the coupon can be used. | The discount type and value cannot be edited after the coupon is created. Create a new coupon when the commercial discount changes. ## Create a coupon 1. Go to **Catalog** > **Coupons**. 2. Click **New coupon**. 3. Enter the coupon **Name** and, if needed, an **Internal description**. 4. Choose the discount type: * **Fixed amount**: select the currency and discount amount. * **Percentage**: enter the percentage discount. 5. Configure optional settings: * **Redemption deadline**: date after which the coupon can no longer be redeemed. * **Redemption limit**: maximum number of times the coupon can be redeemed. * **Eligible products**: products the coupon can apply to. Leave empty to allow all products. 6. Click **Create new coupon**. The coupon appears in the **Coupons** list after creation. ## Apply coupons Coupons can be applied when creating or updating subscriptions, preparing quotes, and editing invoices before they are finalized. When applying a coupon, Hyperline asks how long the discount should apply and which eligible products should receive the discount. Product eligibility comes from the coupon settings, then can be narrowed down for the specific subscription, quote, or invoice. ### Coupon duration When applying a coupon to a subscription, choose how long it should apply: | Duration | Behavior | | ------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **Once** | Applies to a single invoice. Once that invoice is finalized, the coupon expires for the subscription. | | **Relative duration** | Applies for a specific period, such as 3 months or 6 months, from the subscription phase start or transition date. | | **Phase duration** | Applies for the full duration of the current subscription phase. | | **Subscription duration** | Applies for the lifetime of the subscription. | ## Promotion codes Promotion codes are created from a coupon. They let customers enter a code on a checkout page and redeem the coupon themselves. Use promotion codes when you want a self-serve checkout experience, public campaign code, partner code, or customer-specific code. Use coupons directly when your team should apply the discount internally during subscription, quote, or invoice setup. A single coupon can have multiple promotion codes. For example, a **20% annual discount** coupon can power `SPRING20`, `PARTNER20`, and customer-specific codes with different limits. Learn how to configure customer-facing codes in [Promotion codes](./promotion-codes). ## Manage coupons Open a coupon to review its configuration, see its promotion codes, or delete it. Deleting a coupon archives it and prevents future use. It does not remove the coupon from active subscriptions where it has already been applied. ## Next steps * Create customer-facing codes with [Promotion codes](./promotion-codes). * Apply coupons while [assigning a subscription](../subscriptions/create). * Manage coupons during a [subscription update](../subscriptions/update). # Promotion codes Source: https://docs.hyperline.co/docs/coupons/promotion-codes Let customers redeem coupon discounts using promotion codes during Hyperline checkout, with code-level redemption rules and product targeting. Promotion codes are customer-facing codes attached to a coupon. They let customers enter a code during checkout and receive the discount defined by the underlying coupon. A coupon controls the discount itself: fixed amount or percentage, eligible products, and global redemption rules. A promotion code controls how customers can redeem that coupon from checkout: the code value, customer or product eligibility, expiration date, redemption limit, and duration. ## When to use promotion codes Use promotion codes when customers should redeem a discount without your team applying it manually. Common examples include public acquisition campaigns, partner discounts, customer-specific offers, and first-order incentives. Use the coupon directly when the discount should be applied by your team while creating a subscription, preparing a quote, or editing an invoice. Create a **20% annual discount** coupon, then add one promotion code for a public campaign (`SPRING20`) and another for a partner (`PARTNER20`). Both codes apply the same discount, but each code can have its own expiration date, redemption limit, and eligibility rules. ## Create a promotion code Promotion codes are managed from the coupon they redeem. 1. Go to **Catalog** > **Coupons**. 2. Open the coupon you want customers to redeem. 3. In **Promotion codes**, click **Add promotion code**. 4. Enter the **Code** customers will type at checkout. 5. Configure the eligibility and limits. 6. Click **Save changes**. ## Promotion code settings | Setting | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Code** | The value customers enter at checkout, such as `SPRING20` or `PARTNER20`. | | **Customer** | Optional restriction to one customer. Leave empty to make the code available to all customers. | | **Product** | Optional restriction to subscriptions containing a specific product. Leave empty to use the coupon's product eligibility only. | | **Expiration date** | Optional date after which the code can no longer be redeemed. | | **Maximum redemptions** | Optional limit for this promotion code. This is tracked separately from the coupon redemption limit. | | **Duration** | How long the redeemed discount applies after checkout. Leave empty to use the coupon's default duration, or choose a specific duration such as once, days, weeks, months, or years. | | **First order only** | Restricts the code to customers placing their first order. | Promotion code limits do not replace coupon limits. A checkout redemption must satisfy both the promotion code settings and the underlying coupon settings. ## Redeem a promotion code at checkout When at least one promotion code exists on your account, the checkout page displays an **Add promo code** option. Customers can enter a code, apply it, and see the discount reflected in the checkout summary before completing payment. If the code is expired, over its redemption limit, restricted to another customer or product, or otherwise not eligible for the checkout, Hyperline shows an invalid code message and does not apply the discount. ## Manage promotion codes Open the coupon to review all related promotion codes. The list shows each code, redemption count, expiration, duration, and whether it is restricted to first orders. You can edit a promotion code while it is active, or delete it when it should no longer be available at checkout. Deleting a promotion code prevents future redemptions but does not remove discounts already applied to subscriptions. ## Coupons and promotion codes Coupons and promotion codes work together: | Concept | Purpose | Managed by | | ------------------ | ----------------------------------------------------------------- | ---------------------------------------------------------------------- | | **Coupon** | Defines the discount amount, discount type, and base eligibility. | Internal teams applying discounts manually or creating codes. | | **Promotion code** | Defines how a customer can redeem a coupon during checkout. | Teams running campaigns, partner offers, or self-serve checkout flows. | Use one coupon with several promotion codes when the commercial discount is the same but each audience needs different redemption rules. Create separate coupons when the discount value, currency, or product eligibility is different. ## Next steps * Review the underlying [Coupons](./overview) setup. * Learn how checkout pages work in [Checkout page](../subscriptions/checkout-page). # Credits overview Source: https://docs.hyperline.co/docs/credits/overview Set up customer credit balances in Hyperline: configure credit products, expiration, auto top-up, and apply them across plans and subscriptions. This page covers the full credit product lifecycle: catalog setup, customer balances, plan and subscription integration, expiration, and auto-topup. For an introduction to credits as a product type and where they sit in the catalog, see [Products and prices](/docs/products/overview#credit). **Prerequisite** To configure credits, you will need to have connected events first so usage data can be detected. ## Create a credit product To get started with credits, you should create a credit product first in your catalog, where you will specify the events that rule the consumption. Usage of credits will be deducted automatically accordingly. Add one or more [aggregators](/docs/usage/aggregators) to define which events consume credits on the customer's balance. Each aggregator has a **weight** that determines how many credits are consumed per unit of usage. You can add aggregators directly from this form — if you need a new one, click **Create aggregator** to set it up without leaving the page. You can also configure display settings (public description) and set a low balance threshold to trigger warnings on the customer portal. The unit name shown to customers is inherited from the linked aggregator. For credits, the pricing type is bundle pricing, a given price for a number of credits. You can also choose to display different purchase options on the customer's portal. ## Multiple aggregators with weights A credit product can be linked to multiple aggregators, each with its own weight. All aggregators consume from a **single shared balance**, but at different rates. The weight defines how many credits are deducted per unit of usage for that aggregator. For example, a weight of `3` means each unit of usage consumes 3 credits. An AI platform sells credits that can be used across different models: | Aggregator | Operation | Weight | | ------------------ | --------- | ------ | | `gpt4_requests` | count | 5 | | `gpt3_requests` | count | 1 | | `image_generation` | count | 10 | A customer with 1,000 credits could use them for 200 GPT-4 requests, 1,000 GPT-3 requests, 100 image generations, or any combination. If you only need a single aggregator, simply add one row with a weight of `1`. This works exactly like a standard credit product. ## Set up credits on a customer Once your credit product is set up, you can enable a credit balance on your customer and link their credit usage immediately. Note that this can also be done via the API. Here, you can also change the name, choose the starting balance, and set the credit warning limit. This won't override the values previously set in your product catalog, but will be specific to the customer. Once the balance is created, a **credits chart** shows balance evolution over time. You can adjust the date range and granularity (daily, weekly, monthly) to analyze consumption patterns. Below the chart, the **transactions table** lists all credit movements (top-ups, usage, expirations). For products with multiple aggregators, an **Aggregator** column indicates which aggregator triggered each usage transaction. You can click on a usage transaction to inspect and export the underlying consumption events. You can also manually top up or remove credits via the **Actions** menu. ## Add credit products in plan and subscription Credit products created in the product catalog can be added to predefined billing plans and subscriptions like any other product. Options for this product can also be changed at the customer/subscription level, allowing full customization without altering your catalog configuration. ## Consumption order A customer's credit balance is a single shared pool. When usage is reported (via events or via `POST /v1/customers/{id}/credits/{productId}/usage`), it is deducted from that pool. For accounting and expiration purposes, the deducted amount is attributed to individual top-ups in **FIFO order by top-up creation date** — the oldest top-up is drained first, the most recent one last. This applies regardless of whether a top-up has an expiration date or is permanent. Consumption order is based on **when each top-up was created**, not on its expiration date. A permanent top-up created before a time-limited top-up will be drained first. If you want a "free" allowance (e.g. a plan-included monthly allowance) to be consumed before paid top-ups, make sure the allowance top-up is credited to the balance **before** any paid top-up on the same credit product. For recurring allowances tied to a subscription, the allowance is credited at the start of each billing period, so as long as paid top-ups happen after that point, the allowance will be consumed first. ## Credit expiration Credits can be configured to expire automatically, ensuring that unused credits don't remain on customer balances indefinitely. There are two ways to set up credit expiration: ### Expiration after a fixed number of days Set a specific number of days after which credits will expire. This is useful for promotional credits or time-limited offers. When configuring a credit product on a subscription, you can specify how many days after the topup the credits will expire. ### Expiration at the end of the billing period Credits can be configured to expire at the end of each billing period. This is useful for monthly or annual credit allowances that should not roll over. When configuring a credit product on a subscription, you can enable this option. Credits will automatically expire when the billing period ends, and new credits will be added at the start of the next period. When credits expire, an expiration transaction is automatically created in the credit ledger, and the customer's balance is reduced accordingly. The oldest credits expire first. ## Auto-topup Auto-topup allows you to automatically replenish a customer's credit balance when it falls below a specified threshold. This ensures uninterrupted service for your customers and reduces manual intervention. ### How auto-topup works When a customer's credit balance drops below the configured low balance threshold, Hyperline can automatically: 1. Create an invoice for the topup amount 2. Charge the customer's payment method 3. Add the credits to their balance ### Configuration options Auto-topup can be configured in two ways: **Custom amount**: Specify a fixed amount to charge and the number of credits to add when the threshold is reached. **Bundle pricing**: Use an existing bundle price from your product catalog. The system will automatically calculate the correct amount based on the bundle pricing. If you want to add 200 credits and your bundle is 50 credits for €400, the system will charge €1,600 for 4 bundles. ### Setting up auto-topup When creating or updating a credit balance for a customer, you can configure: * The balance threshold that triggers auto-topup * The number of credits to add when triggered * Either a custom amount to charge, or select a bundle price from your catalog Auto-topup requires the customer to have a valid payment method on file. If the payment fails, the topup will not be processed and the balance will remain unchanged. # Customer exports Source: https://docs.hyperline.co/docs/customers/exports Export Hyperline customer data to CSV — including subscriptions, estimated ARR, payment status, and contact details — for external analysis. If you wish to export your customer data for external analysis, Hyperline provides you with built-in file export within the Customers section. ## Export flow After clicking the export button, your customer data will be compiled into a CSV file. Download the file to access a complete export, including customer details, their number of active subscriptions, estimated ARR, and more. # Organisation-based billing Source: https://docs.hyperline.co/docs/customers/organisation-based Bill multiple Hyperline customers under a single parent account with organisation-based billing, while keeping each child's subscriptions distinct. Sometimes you need to bill a group of customers on a single entity without sacrificing the details of each independent account and subscription. The organisation-based billing feature is available directly from the customer page, where you can attach a customer to another. ## Activate organisation-based billing Here, you can see the parent/children relationship and the invoicing configuration for this customer. By clicking "Set parent organisation", you'll be able to choose a parent organisation for this customer. You'll be prompted to choose a parent organisation and then to select an invoicing configuration. 3 options are available at this stage. * `Individual invoices` will move every invoice for the current customer to the parent and invoice it under the parent configuration while keeping the content identical. * `Grouped` will set the current customers invoices as pending and concatenate them regularly with other children from the parent. Concatenated invoices will display one line item per children invoice with the original line items listed in description. * `No change` will attach the child to the parent but will not change any invoicing parameter. If you have chosen `Grouped` for the child invoicing configuration, you'll need to set the grouping schedule on the parent. To do this, go to the parent customer page, click on the dots next to "Org. based billing" and select "Children settings". You'll be able to select a schedule (monthly, quarterly or yearly) and the next invoicing date. From there everything will be automated, but you can adjust the next invoicing date at any time. When going to the parent, you will see all the children and the related settings. A callout will appear on the invoicing section of the children to inform you that the invoices are being billed to the parent. ## Precisions on organisation-based billing **Payment methods** If a customer is billed through a parent, Hyperline will use the parent payment method configuration to process the payment. So for instance if the child customer is connected to Stripe and has a credit card on file, we won't use it. **Draft invoices** When creating parent invoices in organisation-based billing, Hyperline respects the draft invoice setting from child subscriptions: * For `Individual invoices` configuration: if the child subscription has draft invoices enabled, the parent invoice will be created as a draft. * For `Grouped` configuration: if any child subscription has draft invoices enabled, the merged parent invoice will be created as a draft. This applies to all invoices, including zero-amount invoices. **See child invoices** When an invoice from a child is reported to a parent, Hyperline keeps a document specific to the children to make tracking and audits easier. These documents have the status `Charged on parent` and are kept in the child "Invoices" tab. If a child invoice is pending a parent grouped invoicing, it will have the status `Pending parent concat`. **Track line item origins** For `Grouped` configuration, parent invoices include an `original_line_item_id` field on each line item, allowing you to trace which child invoice each line item originated from via the API. **Remove a child company from its parent** In the modal where you linked the child company to its parent, a red button has appeared. If you click on this button, the child company will be removed from the parent and any future invoice will stay on the child. Invoices with the status `Pending parent concat` will move back to the child to get processed. # Customers Source: https://docs.hyperline.co/docs/customers/overview Manage the individuals and companies you bill in Hyperline: create customers manually or via API, track subscriptions, and update billing info. Customers are the individuals or companies that purchase your products or subscribe to your services. We recommend creating a customer in Hyperline as soon as they register for your product. ## Create a customer ### Manual creation Click **New Customer**. Enter the customer details, then click **Save customer**. If you do not have all the information at this time, you can still create the customer and update the details later. Only a name, currency, and country are required. The customer will appear immediately in your customer list (under the `All` filter). Click the customer's name to access their detailed information. On this page, you will see an overview of the customer's information on the left side of the screen. On the right, you can navigate through their [subscriptions](../subscriptions/manage), [wallet](../wallets/overview), [invoices](../invoices/overview), and events. ### Automatic creation Customers can be created programmatically [using the API](../../api-reference/endpoints/customers/create-customer). Additionally, when a CRM is connected and configured to automatically sync customers to Hyperline, customers will be created automatically. ### Default language and country When creating a customer, the language is determined through a cascade: if explicitly provided, that value is used; otherwise, if a country is provided, the language is inferred from that country; if neither is provided, the language defaults to the invoicing entity's language. The country follows a simpler fallback: the provided country is used if available; otherwise, it defaults to the invoicing entity's country. This ensures that every customer has valid language and country settings, even when not explicitly specified. ## Edit a customer Customer information can be updated at any time by clicking **Edit** in the actions dropdown. The **currency** cannot be changed in the following cases: * Once a customer has a wallet with funds or an active payment method (you must remove the payment method and delete the wallet first) * When using an external billing engine (the currency must be managed in the external tool) If you need to change the currency and cannot do so, please contact support. ### Taxability Customer taxability controls whether Hyperline should apply taxes to that customer. * **Taxable** is the default behavior. Hyperline calculates taxes from your tax settings, the customer's billing country, tax ID, and the products being billed. * **Tax exempt** prevents tax from being charged to the customer. Use it only when the customer is exempt from tax for your billing context. If **Require customer tax ID** is enabled in the invoicing entity's tax settings, company customers must have a tax ID before their billing details can be completed. ## Addresses A customer has a billing address that appears on quotes, invoices, and other documents. ### Shipping address By default, the billing address is used as the shipping address. To use a different shipping address, click the **Edit** button on the customer details page. When this option is enabled, customers can edit their shipping address directly from the customer portal. Shipping details can also be displayed on quotes and invoices. Shipping address is subject to activation on our side. Please contact support if you are interested. # Public customer portal Source: https://docs.hyperline.co/docs/customers/portal Give customers a hosted Hyperline portal to manage subscriptions, payment methods, invoices, and billing information across multiple languages. ## Overview Hyperline offers a customer portal where your customers can get access to their live subscription, payment methods, billing information and invoices. Our objective is to ensure a transparent and well-organized billing summary to offer to your own customers. As well as displaying information correctly, this portal offers a number of action options for your customers: #### Portal language The language will be displayed following these rules: * If the customer's browser language is part of our 8 supported languages (English, French, German, Italian, Spanish, Polish, Portuguese and Dutch), it will be displayed in the language. * If it is not part of the supported languages, we will default on the customer language selected on Hyperline customer information. By default, this language is inferred based on the customer's country. #### View subscription details Customers can access the full details of their subscription by clicking on 'Subscription details' on the portal. This sub-page will display the content of the next invoice that will be billed, as well as the detailed price structure of every product. #### Change payment method To do that, they just have to click on the trash button next to their payment and add the new payment method they want to use. #### Top-up wallet You can make your customers autonomous by offering them to top-up their wallet in the portal. For this, make sure you enable the option on the wallet settings first. Clicking on Top-up wallet on this screen will trigger an immediate payment from the registered credit card and credit the wallets instantly. #### Edit billing information To make changes, they simply need to click on the **Edit** button. This grants them the ability to update and modify their billing details as needed, ensuring accuracy and up-to-date information for a seamless payment process. This capability can be controlled in **Settings > Hosted pages**. See the [Billing details update](#billing-details-update) section below for more details. #### Download invoices All invoices are listed and can be open to their dedicated [invoice page](../invoices/invoice-page). Customer can download their invoice PDF using the 'Download' button on the top-right corner. ## How to access the customer portal To view the portal for a specific customer: go to the customer page, select the customer you want to view then click on the 'Portal' button. You can easily provide your customers with this unique portal link. Each customer portal link is individually generated and secured through a unique ID. ## Customize the portal ### Colors & brand identity The portal adopts the primary brand color and icon that have been configured in the 'Settings' section under the 'General' tab of Hyperline. This uses the same codes as those displayed on the invoice sent to your customers. This feature enables you to personalize your customer portal with the distinct colors and branding of your company ### Set a custom domain In order to personalize further the experience for your customers, you can configure a custom domain for the hosted portal and checkout pages. You can set it in [your settings](https://app.hyperline.co/app/settings/hosted-pages), and to enable it you need to add a `CNAME` record pointing to `cname.hyperline.co` on your DNS provider. For example: you want to set your custom domain to `billing.alpeak.com` in Hyperline, and add the related `CNAME` record on your DNS provider, we will provide you portal and checkout URLs with the form: ``` https://billing.alpeak.com/portal/:customerId https://billing.alpeak.com/checkout/:sessionId ``` We will automatically manage the related HTTPS SSL certificate. ### Customer actions You can control what actions customers can perform on hosted pages through **Settings > Hosted pages** under the **Customer actions** section: #### Billing details update You can control whether customers can update their billing details (billing address, billing email, tax ID, and invoice emails) on hosted pages through **Settings > Hosted pages** under the **Customer actions** section. Toggle **Allow billing details update** to enable or disable this capability. When enabled, customers will be able to edit their billing information through the customer portal, checkout, and quote pages. #### Customer typology selection By default, hosted pages (customer portal, checkout, and quote pages) allow customers to select between B2C (person) and B2B (corporate) typologies when updating their billing information. You can disable this typology selection in **Settings > Hosted pages** under the **Customer actions** section. When disabled, customers will not be able to change their typology on hosted pages, and the form will use their existing typology setting. #### Payment method deletion You can control whether customers can delete their **default** payment method on hosted pages through **Settings > Hosted pages** under the **Customer actions** section. Toggle **Allow payment method deletion** to enable or disable this capability. Non-default payment methods can always be deleted regardless of this setting. When deletion is disabled, customers can still delete a default payment method if it is **irreversibly errored** — meaning the card or mandate is permanently dead and cannot be recovered. This covers the following error reasons: * `Expired` — the card or mandate has expired. * `MandateInvalid` — the mandate is no longer valid. Default payment methods in a **recoverable** error state (for example `InsufficientFunds`, `AuthenticationRequired`, `Declined`, `Fraud`, `Invalid`, `NotSupported`, `AuthorizationError`, or `Unknown`) remain locked, as the customer is expected to retry or re-authenticate rather than delete the payment method. ### Generate a portal link You can generate a portal link for a specific customer in two ways: * **API**: call `GET /v1/customers/{id}/portal` to retrieve the portal URL. See the [endpoint reference](/api-reference/endpoints/customers/get-customer-portal). * **App**: click the **Portal** button on the customer page (see [How to access the customer portal](#how-to-access-the-customer-portal)). The returned link embeds an authentication token. It is valid for the duration set in **Link expiration delay**, or indefinitely if the delay is empty. After expiry, behavior depends on whether **Require customer authentication** is enabled — see [Authentication vs. link expiration](#authentication-vs-link-expiration). ### Portal authentication You can require customers to authenticate before accessing the customer portal through **Settings > Hosted pages > Security**. When enabled, customers without a valid token must verify their identity via a magic link sent to their email address before they can view their portal. #### How it works Portal links contain an authentication token. **Link expiration delay** controls how long that token is valid; **Require customer authentication** controls what happens when no valid token is present. When authentication is required and a customer opens the portal without a valid token (first visit, expired token, or direct URL): 1. The portal shows a login screen. 2. The customer enters an email matching their billing email or invoice emails. 3. A magic link is sent to that email. 4. Clicking the magic link grants access — indefinitely if no link expiration is set, otherwise for the configured window. Portal authentication adds an extra layer of security by ensuring only authorized users can access customer billing information. Useful for B2B customers where multiple people might share portal links. #### Authentication vs. link expiration Portal authentication and **Link expiration delay** combine to control access: * **Auth off, no expiration**: portal links work indefinitely (default). * **Auth off, expiration set**: tokens expire after the configured delay; revisiting the URL automatically issues a new token, no login required. * **Auth on, no expiration**: customers without a valid token are sent to the login screen. After authenticating via magic link, the issued token never expires (one-time auth, permanent access). * **Auth on, expiration set**: links work for the configured window. After expiry, customers must re-authenticate via magic link to obtain a new token. When authentication is required, every visit without a valid token redirects to the login screen. Communicate this to your customers if you change the setting. ### Link expiration delay By default, hosted page URLs (customer portal, checkout, and quote pages) contain authentication tokens that never expire. You can configure an expiration in **Settings > Hosted pages > Domain > Link expiration delay** (in minutes). When set: * Tokens are included in all hosted page URLs (both Hyperline-hosted and custom domain URLs). * After the delay, customers need a new link or must re-authenticate to access the page. * Applies to portal links, checkout session links, and quote links. Link expiration enhances security by limiting how long a shared link remains valid. Useful when links are sent via email or other channels where they might be forwarded. ### Set a redirect button You can configure a back button in the hosted pages settings. And it will look like this in the portal ### Display personalization You can add this query parameter to your portal URL to hide the sidebar `&hideSidebar=true`. It will look like this: It works both for custom domain and hyperline hosted pages. ### Embed the customer portal in an iframe You can embed the Hyperline customer portal inside your application using an `