# Create ledger account Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-accounts/create-ledger-account post /v1/accounting/accounts Create an account in an accounting ledger. # Delete ledger account Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-accounts/delete-ledger-account delete /v1/accounting/accounts/{id} Delete an unused accounting ledger account. # Get ledger account Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-accounts/get-ledger-account get /v1/accounting/accounts/{id} Retrieve a ledger account by its identifier. # List ledger accounts Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-accounts/list-ledger-accounts get /v1/accounting/accounts List accounting ledger accounts with optional balances. # List primary accounts Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-accounts/list-primary-accounts get /v1/accounting/primary-ledger/accounts List accounts from the primary ledger of an invoicing entity. # Update ledger account Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-accounts/update-ledger-account put /v1/accounting/accounts/{id} Update an existing ledger account. # Create journal entry Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-journal-entries/create-journal-entry post /v1/accounting/journal-entries Create and post a balanced manual journal entry attributed to the current user or API credential. # Get journal entry Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-journal-entries/get-journal-entry get /v1/accounting/journal-entries/{id} Retrieve a journal entry and its lines by identifier. # List journal entries Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-journal-entries/list-journal-entries get /v1/accounting/journal-entries List accounting journal entries with optional filters. # List journal entry lines Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-journal-entries/list-journal-entry-lines get /v1/accounting/journal-entry-lines List journal entry lines with optional filters. # Preview recognition schedule Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-journal-entries/preview-recognition-schedule post /v1/accounting/journal-entries/recognition-preview Preview revenue-recognition slices for a manual journal entry without writing data. # Create ledger Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-ledgers/create-ledger post /v1/accounting/ledgers Create an accounting ledger for an invoicing entity. # Delete ledger Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-ledgers/delete-ledger delete /v1/accounting/ledgers/{id} Permanently delete a ledger with its accounts, rules, journal entries and revenue recognition schedules, and unlink the suppliers, supplier contracts and accounting settings that reference it. # Get ledger Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-ledgers/get-ledger get /v1/accounting/ledgers/{id} Retrieve an accounting ledger by its identifier. # List ledgers Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-ledgers/list-ledgers get /v1/accounting/ledgers List accounting ledgers for the authenticated client. # Update ledger Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-ledgers/update-ledger put /v1/accounting/ledgers/{id} Update an existing accounting ledger. # Export general ledger Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-reports/export-general-ledger post /v1/accounting/general-ledger/export Queue an XLSX general-ledger export for a ledger and inclusive period. # Export income statement Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-reports/export-income-statement post /v1/accounting/income-statement/export Queue an XLSX income-statement export for a ledger and inclusive period. # Export recognized revenue summary Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-revenue-recognition/export-recognized-revenue-summary post /v1/accounting/revrec/recognized-summary/export Queue an XLSX or CSV summary of recognized revenue for a month range. # Export revenue recognition waterfall Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-revenue-recognition/export-revenue-recognition-waterfall post /v1/accounting/revrec/waterfall/export Queue an XLSX waterfall export for a ledger and year. # Get revenue recognition schedule Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-revenue-recognition/get-revenue-recognition-schedule get /v1/accounting/revrec/schedules/{id} Retrieve a revenue-recognition schedule with its slices. # Get revenue recognition slice Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-revenue-recognition/get-revenue-recognition-slice get /v1/accounting/revrec/slices/{id} Retrieve a tenant-scoped revenue-recognition slice. # Get revenue recognition waterfall Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-revenue-recognition/get-revenue-recognition-waterfall get /v1/accounting/revrec/waterfall Aggregate revenue-recognition schedules into a booked-by-recognition month matrix. # Get revenue recognition waterfall cell Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-revenue-recognition/get-revenue-recognition-waterfall-cell get /v1/accounting/revrec/waterfall/cell List the schedules and slices contributing to a waterfall cell. # Get unbilled revenue Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-revenue-recognition/get-unbilled-revenue get /v1/accounting/revrec/unbilled Get revenue accrued on a subscription's current open invoice. # List revenue recognition adjustments Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-revenue-recognition/list-revenue-recognition-adjustments get /v1/accounting/revrec/schedules/{schedule_id}/adjustments List the audit trail for manual schedule adjustments. # List revenue recognition schedules Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-revenue-recognition/list-revenue-recognition-schedules get /v1/accounting/revrec/schedules List revenue-recognition schedules with embedded slices. # Preview revenue recognition reshape Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-revenue-recognition/preview-revenue-recognition-reshape post /v1/accounting/revrec/schedules/{schedule_id}/reshape/preview Preview the exact reshape plan without writing data. # Reshape revenue recognition schedule Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-revenue-recognition/reshape-revenue-recognition-schedule post /v1/accounting/revrec/schedules/{schedule_id}/reshape Recognize an amount now and optionally spread the remainder over a new window. # Create accounting rule Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-rules/create-accounting-rule post /v1/accounting/rules Create a new accounting rule for account code routing or journal posting. # Delete accounting rule Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-rules/delete-accounting-rule delete /v1/accounting/rules/{id} Soft-delete an accounting rule. # Get accounting rule Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-rules/get-accounting-rule get /v1/accounting/rules/{id} Retrieve a single accounting rule by its identifier. # Get accounting rule tree Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-rules/get-accounting-rule-tree get /v1/accounting/rules/tree Retrieve accounting rules organized as a filter tree. Accounting software sync rules are excluded. # Get rule defaults Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-rules/get-rule-defaults post /v1/accounting/rules/defaults Preview default account values and priority for a new accounting rule. # List accounting rules Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-rules/list-accounting-rules get /v1/accounting/rules Retrieve existing accounting rules with optional filtering. # Resolve accounting rule Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-rules/resolve-accounting-rule post /v1/accounting/rules/resolve Preview which account codes would be resolved for a given context. # Update accounting rule Source: https://docs.hyperline.co/api-reference/endpoints/accounting->-rules/update-accounting-rule put /v1/accounting/rules/{id} Update an existing accounting rule. # Get aggregator usage Source: https://docs.hyperline.co/api-reference/endpoints/aggregators->-usage/get-aggregator-usage get /v1/aggregators/{id}/usage Retrieve a usage row for an aggregator (name, unit and thresholds). # Get aggregator usage events Source: https://docs.hyperline.co/api-reference/endpoints/aggregators->-usage/get-aggregator-usage-events get /v1/aggregators/{id}/usage/events List raw billable events for an aggregator across every customer of the client. # Get aggregator usage grouped by customer Source: https://docs.hyperline.co/api-reference/endpoints/aggregators->-usage/get-aggregator-usage-grouped-by-customer get /v1/aggregators/{id}/usage/group-by-customer Per-customer total usage for an aggregator over a period, ordered by total DESC, paginated. # Get aggregator usage timeseries Source: https://docs.hyperline.co/api-reference/endpoints/aggregators->-usage/get-aggregator-usage-timeseries get /v1/aggregators/{id}/usage/timeseries Get client-wide usage for an aggregator bucketed by month, day or hour. # Create aggregator Source: https://docs.hyperline.co/api-reference/endpoints/aggregators/create-aggregator post /v1/aggregators Create a new aggregator. # Delete aggregator Source: https://docs.hyperline.co/api-reference/endpoints/aggregators/delete-aggregator delete /v1/aggregators/{id} Delete an existing aggregator. # Get aggregator Source: https://docs.hyperline.co/api-reference/endpoints/aggregators/get-aggregator get /v1/aggregators/{id} Retrieve the details of an existing aggregator. # List aggregators Source: https://docs.hyperline.co/api-reference/endpoints/aggregators/list-aggregators get /v1/aggregators Retrieve existing aggregators. # Update aggregator Source: https://docs.hyperline.co/api-reference/endpoints/aggregators/update-aggregator put /v1/aggregators/{id} Update the details of an existing aggregator. # Apply default billing plan Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/apply-default-billing-plan post /v1/ai/billing/customers/{id}/apply-default-plan Apply the workspace default to an unconfigured customer, return applied false without changes when already attached, or return 409 for another arrangement. # Clear default billing plan Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/clear-default-billing-plan delete /v1/ai/billing/plans/default Clear the workspace default without deleting the plan, or return 404 when unset. # Clear product AI rate card Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/clear-product-ai-rate-card delete /v1/ai/billing/products/{id}/rate-card Detach a credit product's default AI rate card without deleting the card, or return 404 when none is attached. # Configure billing policy Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/configure-billing-policy put /v1/ai/billing/customers/{id}/policies/agents/{agent_slug} Replace customer billing settings while preserving omitted plan_id and rate_card_id references; null detaches them, and a shared policy enables automatic telemetry billing. # Configure default billing policy Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/configure-default-billing-policy put /v1/ai/billing/customers/{id}/policies/default Replace customer billing settings while preserving omitted plan_id and rate_card_id references; null detaches them, and a shared policy enables automatic telemetry billing. # Create billing plan Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/create-billing-plan post /v1/ai/billing/plans Create an AI billing plan; metered overage also provisions the catalog products needed for invoicing. # Create rate card Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/create-rate-card post /v1/ai/billing/rate-cards Create a reusable AI rate card with token and item prices in credits, allowance units or currency. # Delete billing plan Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/delete-billing-plan delete /v1/ai/billing/plans/{id} Delete an unused billing plan, or return 409 while customer policies still reference it. # Delete rate card Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/delete-rate-card delete /v1/ai/billing/rate-cards/{id} Delete an unused rate card, or return 409 while a plan, product or policy references it. # Get billing balance Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/get-billing-balance get /v1/ai/billing/customers/{id}/balance Get the live shared-pool balance and agent scopes, or the effective balance for agent_slug with fallback to the shared pool. # Get billing plan Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/get-billing-plan get /v1/ai/billing/plans/{id} Get an AI billing plan by ID. # Get billing policy Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/get-billing-policy get /v1/ai/billing/customers/{id}/policies/agents/{agent_slug} Get the shared policy or the exact agent_slug override, returning 404 when that scope has no policy of its own. # Get default billing plan Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/get-default-billing-plan get /v1/ai/billing/plans/default Get the workspace default plan reference and auto-apply setting, or 404 when unset. # Get default billing policy Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/get-default-billing-policy get /v1/ai/billing/customers/{id}/policies/default Get the shared policy or the exact agent_slug override, returning 404 when that scope has no policy of its own. # Get product AI rate card Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/get-product-ai-rate-card get /v1/ai/billing/products/{id}/rate-card Get the default AI rate-card reference for a credit product, or 404 when none is attached. # Get rate card Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/get-rate-card get /v1/ai/billing/rate-cards/{id} Get a rate card with its pricing rows and dependency counts. # List billing plans Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/list-billing-plans get /v1/ai/billing/plans List reusable AI billing plans, filtered by mode and paginated with take/skip. # List billing policies Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/list-billing-policies get /v1/ai/billing/customers/{id}/policies List configured customer billing scopes with take/skip; agent_slug null identifies the shared pool. # List consumption Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/list-consumption get /v1/ai/billing/customers/{id}/consumption List billed ledger entries with take/skip, dates and overage filters; omitted agent_slug includes all scopes and an empty string selects the shared pool. # List rate cards Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/list-rate-cards get /v1/ai/billing/rate-cards List AI rate cards filtered by denomination, currency or name and paginated with take/skip. # Remove billing policy Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/remove-billing-policy delete /v1/ai/billing/customers/{id}/policies/agents/{agent_slug} Remove a configured billing scope while preserving its ledger, refusing unsettled consumption or dependent overrides with 409. # Remove default billing policy Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/remove-default-billing-policy delete /v1/ai/billing/customers/{id}/policies/default Remove a configured billing scope while preserving its ledger, refusing unsettled consumption or dependent overrides with 409. # Replace billing plan Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/replace-billing-plan put /v1/ai/billing/plans/{id} Replace all mutable plan settings for future usage; omitted settings reset and mode remains immutable. # Replace rate card Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/replace-rate-card put /v1/ai/billing/rate-cards/{id} Replace the complete pricing row set and mutable settings for future usage; denomination and currency remain immutable. # Reset allowance windows Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/reset-allowance-windows post /v1/ai/billing/customers/{id}/windows/reset Close the exact scope’s open allowance windows so the next usage starts fresh; available only in windows mode. # Set default billing plan Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/set-default-billing-plan put /v1/ai/billing/plans/default Set the workspace default plan and whether eligible new customers receive it automatically. # Set product AI rate card Source: https://docs.hyperline.co/api-reference/endpoints/ai->-billing/set-product-ai-rate-card put /v1/ai/billing/products/{id}/rate-card Attach a credits-denominated AI rate card with complete fallback pricing as the credit product's default. # Create custom cost item Source: https://docs.hyperline.co/api-reference/endpoints/ai->-costs/create-custom-cost-item post /v1/ai/billing/costs/items Create a custom provider/item cost; an existing pair returns 200 with its unchanged rates, so use PUT /v1/ai/billing/costs/items/:id to edit it. # List cost catalog Source: https://docs.hyperline.co/api-reference/endpoints/ai->-costs/list-cost-catalog get /v1/ai/billing/costs List provider costs, negotiated overrides and custom items with enablement and pricing provenance; supports take/skip and enabled_only. # Remove custom cost item Source: https://docs.hyperline.co/api-reference/endpoints/ai->-costs/remove-custom-cost-item delete /v1/ai/billing/costs/items/{id} Close a custom item by custom_item_id while preserving historical prices; new usage becomes unpriced unless another price matches. # Remove provider cost override Source: https://docs.hyperline.co/api-reference/endpoints/ai->-costs/remove-provider-cost-override delete /v1/ai/billing/costs/overrides/{id} Close a negotiated cost override and restore registry pricing for future usage. # Replace custom cost item Source: https://docs.hyperline.co/api-reference/endpoints/ai->-costs/replace-custom-cost-item put /v1/ai/billing/costs/items/{id} Replace a custom item's provider, item and dimensions, preserving historical prices and returning the new active custom_item_id. # Set provider cost override Source: https://docs.hyperline.co/api-reference/endpoints/ai->-costs/set-provider-cost-override put /v1/ai/billing/costs/overrides Set negotiated USD costs for a registry model, effective immediately while preserving historical prices. # Check AI spend allowance Source: https://docs.hyperline.co/api-reference/endpoints/ai->-ingest/check-ai-spend-allowance post /v1/ai/billing/check Ask whether a customer may spend right now. A read only — it reserves nothing. A customer with no billing policy is answered with `allowed: false, reason: "not_configured"` rather than an error, so an agent always gets a verdict it can act on. # Consume AI usage Source: https://docs.hyperline.co/api-reference/endpoints/ai->-ingest/consume-ai-usage post /v1/ai/billing/consume Explicit consumption is only for customers without automatic telemetry billing; configuring a shared billing policy normally makes this return 409 telemetry_managed. Record what a customer consumed and charge it against their balance. Hyperline prices the usage itself and applies the policy markup — an amount sent by the caller is never read. The call writes one append-only ledger entry and updates the customer's balance atomically. Replaying an `idempotency_key` returns the original result unchanged. How it charges depends on the customer's mode. In `wallet` mode the usage is priced against the workspace's resolved rates in the wallet's minor units, and the wallet ledger is not touched — a background settlement rolls entries up separately. In `credits` mode it is priced against the policy's credit rate card and the customer's credit balance is decremented for real, in the same transaction, with no settlement afterwards; a customer without enough credits is refused with a 402 and nothing is deducted, so a call is never partially charged. In `windows` mode the usage is weighted into units and metered against every one of the customer's overlapping rolling allowances — a 5h and a 7d window, say. Each window instance is anchored at the first call after the previous one expired and runs for exactly its duration, so `resets_at` is a real instant rather than a moving average. Every window meters every call, and a call that does not fit in *all* of them is refused whole with a 402 carrying `meters` and the soonest `resets_at`: no window is incremented, so a refused call leaves no trace. # Get AI billing snapshot Source: https://docs.hyperline.co/api-reference/endpoints/ai->-ingest/get-ai-billing-snapshot get /v1/ai/billing/snapshot The customer's consumption state: mode, balance, kill switch and policy. `balance` carries the same three numbers in either mode with a `denomination` saying what they count, so a consumer that only wants "how much is left" never has to branch. `credits` is populated in credits mode with the pot, its upcoming expiries and a summary of the rate card; `meters` is populated in windows mode with one live entry per rolling allowance — used, remaining and the instant it resets, counting the open instance — which is the read to poll for a limits UI. # Ingest AI calls Source: https://docs.hyperline.co/api-reference/endpoints/ai->-ingest/ingest-ai-calls post /v1/ai/calls Ingest a batch of AI records (limited to max 2000 per request) — model calls and non-LLM cost items, told apart by `record_kind` (omitted means `llm_call`). Records are processed asynchronously; a record with the same id is deduplicated on storage. # Get analytics Source: https://docs.hyperline.co/api-reference/endpoints/analytics/get-analytics get /v1/analytics Retrieve your pre-computed account's analytics (ARR, revenues, churn, etc). # Create approval workflow Source: https://docs.hyperline.co/api-reference/endpoints/approval-workflows/create-approval-workflow post /v1/approvals/workflows Create a new approval workflow. # Delete approval workflow Source: https://docs.hyperline.co/api-reference/endpoints/approval-workflows/delete-approval-workflow delete /v1/approvals/workflows/{id} Delete an existing approval workflow. # Get approval workflow Source: https://docs.hyperline.co/api-reference/endpoints/approval-workflows/get-approval-workflow get /v1/approvals/workflows/{id} Retrieve a single approval workflow. # List approval workflows Source: https://docs.hyperline.co/api-reference/endpoints/approval-workflows/list-approval-workflows get /v1/approvals/workflows Retrieve approval workflows with optional filtering. # Update approval workflow Source: https://docs.hyperline.co/api-reference/endpoints/approval-workflows/update-approval-workflow put /v1/approvals/workflows/{id} Update an existing approval workflow. # List audit logs Source: https://docs.hyperline.co/api-reference/endpoints/audit-logs/list-audit-logs get /v1/audit-logs Retrieve existing audit logs, including the actor that triggered each event. Sorted by `happened_at` descending. # Get bank account Source: https://docs.hyperline.co/api-reference/endpoints/bank-accounts/get-bank-account get /v1/bank-accounts/{id} Retrieve a specific bank account by ID. # List bank accounts Source: https://docs.hyperline.co/api-reference/endpoints/bank-accounts/list-bank-accounts get /v1/bank-accounts Retrieve existing bank accounts. # List bank transactions Source: https://docs.hyperline.co/api-reference/endpoints/bank-accounts/list-bank-transactions get /v1/bank-accounts/{id}/transactions Retrieve transactions for a specific connected bank account. # Delete billable events Source: https://docs.hyperline.co/api-reference/endpoints/billable-events/delete-billable-events delete /v1/events Delete existing billable events. # Get events Source: https://docs.hyperline.co/api-reference/endpoints/billable-events/get-events get /v1/events Retrieve billable events filtered by event type. # Ingest billable event Source: https://docs.hyperline.co/api-reference/endpoints/billable-events/ingest-billable-event post /v1/events Ingest a new billable event. This endpoint is idempotent, an event with the same id will be updated if it already exists. # Ingest billable events Source: https://docs.hyperline.co/api-reference/endpoints/billable-events/ingest-billable-events post /v1/events/batch Ingest several billable events in batch (limited to max 5000 events per request). This endpoint is idempotent, an event with the same id, will be updated if it already exists. # Create catalog draft Source: https://docs.hyperline.co/api-reference/endpoints/catalog/create-catalog-draft post /v1/catalog/versions/draft Create the pending draft from the current live catalog. Returns the existing draft when one is already pending. # Discard catalog draft Source: https://docs.hyperline.co/api-reference/endpoints/catalog/discard-catalog-draft delete /v1/catalog/versions/draft Archive the pending catalog draft without applying its changes. # Export catalog Source: https://docs.hyperline.co/api-reference/endpoints/catalog/export-catalog get /v1/catalog/export Export the live product catalog resources for the authenticated organisation. # Get catalog draft Source: https://docs.hyperline.co/api-reference/endpoints/catalog/get-catalog-draft get /v1/catalog/versions/draft Retrieve the pending catalog draft, or null when no draft exists. # Get catalog version Source: https://docs.hyperline.co/api-reference/endpoints/catalog/get-catalog-version get /v1/catalog/versions/{id} Retrieve a single catalog version. # List catalog versions Source: https://docs.hyperline.co/api-reference/endpoints/catalog/list-catalog-versions get /v1/catalog/versions Retrieve the product catalog versions: the pending draft followed by published versions. Requires catalog versioning to be enabled. # Publish catalog draft Source: https://docs.hyperline.co/api-reference/endpoints/catalog/publish-catalog-draft post /v1/catalog/versions/draft/publish Apply the pending draft to the live catalog and mark it as a published version. # Revert catalog version Source: https://docs.hyperline.co/api-reference/endpoints/catalog/revert-catalog-version post /v1/catalog/versions/{id}/revert Publish a new catalog version restoring the state of a previous published version (revert). Fails while a draft is pending. # Create company Source: https://docs.hyperline.co/api-reference/endpoints/companies/create-company post /v1/companies Create a company with an approved account owner and company creation enabled, returning 403 if the owner is unapproved. # List companies Source: https://docs.hyperline.co/api-reference/endpoints/companies/list-companies get /v1/companies Retrieve all companies that the authentication token has access to. # Create promotion code Source: https://docs.hyperline.co/api-reference/endpoints/coupons->-promotion-codes/create-promotion-code post /v1/promotion-codes Create a new promotion code. # Delete promotion code Source: https://docs.hyperline.co/api-reference/endpoints/coupons->-promotion-codes/delete-promotion-code delete /v1/promotion-codes/{id} Delete an existing promotion code. # Get promotion code Source: https://docs.hyperline.co/api-reference/endpoints/coupons->-promotion-codes/get-promotion-code get /v1/promotion-codes/{id} Retrieve the details of an existing promotion code. # List promotion codes Source: https://docs.hyperline.co/api-reference/endpoints/coupons->-promotion-codes/list-promotion-codes get /v1/promotion-codes Retrieve existing promotion codes. # Update promotion code Source: https://docs.hyperline.co/api-reference/endpoints/coupons->-promotion-codes/update-promotion-code patch /v1/promotion-codes/{id} Update the details of an existing promotion code. # Create coupon Source: https://docs.hyperline.co/api-reference/endpoints/coupons/create-coupon post /v1/coupons Create a new coupon. # Delete coupon Source: https://docs.hyperline.co/api-reference/endpoints/coupons/delete-coupon delete /v1/coupons/{id} Delete an existing coupon. # Get coupon Source: https://docs.hyperline.co/api-reference/endpoints/coupons/get-coupon get /v1/coupons/{id} Retrieve the details of an existing coupon. # List coupons Source: https://docs.hyperline.co/api-reference/endpoints/coupons/list-coupons get /v1/coupons Retrieve existing coupons. # Update coupon Source: https://docs.hyperline.co/api-reference/endpoints/coupons/update-coupon put /v1/coupons/{id} Update the details of an existing coupon. # Create custom property Source: https://docs.hyperline.co/api-reference/endpoints/custom-properties/create-custom-property post /v1/custom-properties Create a new custom property. # Delete custom property Source: https://docs.hyperline.co/api-reference/endpoints/custom-properties/delete-custom-property delete /v1/custom-properties/{id} Delete an existing custom property. # List custom properties Source: https://docs.hyperline.co/api-reference/endpoints/custom-properties/list-custom-properties get /v1/custom-properties Retrieve all custom properties previously created. # Update custom property Source: https://docs.hyperline.co/api-reference/endpoints/custom-properties/update-custom-property put /v1/custom-properties/{id} Update an existing custom property. # Create address Source: https://docs.hyperline.co/api-reference/endpoints/customers->-address/create-address post /v1/customers/{customerId}/addresses Create a shipping address with type shipping; billing creation is rejected because a customer can have at most one billing address, managed through the customer endpoint. # Delete address Source: https://docs.hyperline.co/api-reference/endpoints/customers->-address/delete-address delete /v1/customers/{customerId}/addresses/{addressId} Delete an address. To delete the default shipping address, first select another shipping address or use the billing address. # List addresses Source: https://docs.hyperline.co/api-reference/endpoints/customers->-address/list-addresses get /v1/customers/{customerId}/addresses List active addresses: at most one billing address and multiple shipping addresses per customer. # Update address Source: https://docs.hyperline.co/api-reference/endpoints/customers->-address/update-address patch /v1/customers/{customerId}/addresses/{addressId} Update a billing or shipping address by ID; billing changes also update the customer billing-address projection. # Create credit product Source: https://docs.hyperline.co/api-reference/endpoints/customers->-credits/create-credit-product post /v1/customers/{id}/credits Create a credit entity for a given product with an optional balance. # Create credits usage Source: https://docs.hyperline.co/api-reference/endpoints/customers->-credits/create-credits-usage post /v1/customers/{id}/credits/{productId}/usage Create a usage entry for a credit product. This will impact the balance of the customer by `usage_retained`. # Get credit portal settings Source: https://docs.hyperline.co/api-reference/endpoints/customers->-credits/get-credit-portal-settings get /v1/customers/{id}/credits/{productId}/portal-settings Retrieve whether a customer can buy a credit product from the customer portal, the price they pay, and the prices they can be given. # Get credit product Source: https://docs.hyperline.co/api-reference/endpoints/customers->-credits/get-credit-product get /v1/customers/{id}/credits/{productId} Retrieve the details of an existing credit product for a customer. # List all credit products Source: https://docs.hyperline.co/api-reference/endpoints/customers->-credits/list-all-credit-products get /v1/customers/credits Retrieve credit products for all customers. # List credit products Source: https://docs.hyperline.co/api-reference/endpoints/customers->-credits/list-credit-products get /v1/customers/{id}/credits Retrieve credit products attached to a customer. # List credit transactions Source: https://docs.hyperline.co/api-reference/endpoints/customers->-credits/list-credit-transactions get /v1/customers/{id}/credits/{productId}/transactions Retrieve all credit transactions associated with a credit product. # Purchase credits Source: https://docs.hyperline.co/api-reference/endpoints/customers->-credits/purchase-credits post /v1/customers/{id}/credits/{productId}/purchase Purchase a number of credits. This action generates an invoice and charges the customer's card immediately; the credits are granted only once the charge succeeds. The customer's payment method must be a card: any other payment method fails with reason `payment_method_not_supported`. # Topup credits Source: https://docs.hyperline.co/api-reference/endpoints/customers->-credits/topup-credits post /v1/customers/{id}/credits/{productId}/topup Topup a number of free credits. This action will not charge the customer. # Update credit portal settings Source: https://docs.hyperline.co/api-reference/endpoints/customers->-credits/update-credit-portal-settings put /v1/customers/{id}/credits/{productId}/portal-settings Enable or disable portal top-ups of a credit product for a customer. Enabling sets the price they pay: one of the product's price configurations, or a price of the customer's own. Enabling requires the customer's credit balance for the product (create it first, even with a 0 balance); otherwise the request fails with reason `credit_balance_required`. # Update credit product Source: https://docs.hyperline.co/api-reference/endpoints/customers->-credits/update-credit-product put /v1/customers/{id}/credits/{productId} Update the configuration of a customer's credit product. # Update credit topup expiration Source: https://docs.hyperline.co/api-reference/endpoints/customers->-credits/update-credit-topup-expiration patch /v1/customers/{id}/credits/{productId}/transactions/{transactionId} Update the expiration date of a topup credit transaction. Only non-expired topup transactions can be updated. # Delete customer feature Source: https://docs.hyperline.co/api-reference/endpoints/customers->-features/delete-customer-feature delete /v1/customers/{id}/features/{code} Delete a feature override from a customer. # Resolve customer features Source: https://docs.hyperline.co/api-reference/endpoints/customers->-features/resolve-customer-features get /v1/customers/{id}/features Resolve feature values for a customer. # Set customer feature Source: https://docs.hyperline.co/api-reference/endpoints/customers->-features/set-customer-feature put /v1/customers/{id}/features/{code} Set a feature override for a customer. # Create payment method Source: https://docs.hyperline.co/api-reference/endpoints/customers->-payment-methods/create-payment-method post /v1/customers/{id}/payment-methods Import an existing customer payment method from a connected payment provider. # Delete payment method Source: https://docs.hyperline.co/api-reference/endpoints/customers->-payment-methods/delete-payment-method delete /v1/customers/{id}/payment-methods/{paymentMethodId} Delete an existing customer payment method. # Get payment method Source: https://docs.hyperline.co/api-reference/endpoints/customers->-payment-methods/get-payment-method get /v1/customers/{id}/payment-methods/{paymentMethodId} Retrieve the details of an existing customer payment method. # List payment methods Source: https://docs.hyperline.co/api-reference/endpoints/customers->-payment-methods/list-payment-methods get /v1/customers/{id}/payment-methods Retrieve payment methods attached to a customer. # Create segment Source: https://docs.hyperline.co/api-reference/endpoints/customers->-segments/create-segment post /v1/customers/segments Create a new customer segment. # Delete segment Source: https://docs.hyperline.co/api-reference/endpoints/customers->-segments/delete-segment delete /v1/customers/segments/{id} Delete an existing customer segment. # Get segment Source: https://docs.hyperline.co/api-reference/endpoints/customers->-segments/get-segment get /v1/customers/segments/{id} Retrieve the details of an existing customer segment. # List segments Source: https://docs.hyperline.co/api-reference/endpoints/customers->-segments/list-segments get /v1/customers/segments Retrieve all customer segments. # Update segment Source: https://docs.hyperline.co/api-reference/endpoints/customers->-segments/update-segment patch /v1/customers/segments/{id} Update an existing customer segment. # Get shipping destination Source: https://docs.hyperline.co/api-reference/endpoints/customers->-shipping/get-shipping-destination get /v1/customers/{customerId}/shipping Get the billing or shipping destination and its resolved address object, or null if no address exists. # Set shipping destination Source: https://docs.hyperline.co/api-reference/endpoints/customers->-shipping/set-shipping-destination put /v1/customers/{customerId}/shipping Select a saved shipping address or use the billing address. # Get customer usage events Source: https://docs.hyperline.co/api-reference/endpoints/customers->-usage/get-customer-usage-events get /v1/customers/{id}/usage/{aggregator_id}/events List raw billable events for a customer and a specific aggregator over a period. # Get customer usage for an aggregator Source: https://docs.hyperline.co/api-reference/endpoints/customers->-usage/get-customer-usage-for-an-aggregator get /v1/customers/{id}/usage/{aggregator_id} Get the usage of a customer for a specific aggregator over a period. # Get customer usage timeseries Source: https://docs.hyperline.co/api-reference/endpoints/customers->-usage/get-customer-usage-timeseries get /v1/customers/{id}/usage/{aggregator_id}/timeseries Get the usage of a customer for an aggregator bucketed by month, day or hour. # List customer usage Source: https://docs.hyperline.co/api-reference/endpoints/customers->-usage/list-customer-usage get /v1/customers/{id}/usage List one usage row per aggregator for a single customer over a period. Use `GET /v1/aggregators/{id}/usage/group-by-customer` for the inverse: one row per customer for a single aggregator. # Archive customer Source: https://docs.hyperline.co/api-reference/endpoints/customers/archive-customer put /v1/customers/{id}/archive Archive an existing customer. # Bulk update providers/customers mapping Source: https://docs.hyperline.co/api-reference/endpoints/customers/bulk-update-providerscustomers-mapping post /v1/customers/providers-bulk-update Bulk update providers/customers mapping, make sure to check the query response to see if all customers were updated. # Create customer Source: https://docs.hyperline.co/api-reference/endpoints/customers/create-customer post /v1/customers Create a new customer. # Create customers batch Source: https://docs.hyperline.co/api-reference/endpoints/customers/create-customers-batch post /v1/customers/batch Create a batch of new customers. # Delete customer Source: https://docs.hyperline.co/api-reference/endpoints/customers/delete-customer delete /v1/customers/{id} Delete an existing customer. The customer must be archived prior to the deletion. # Get customer Source: https://docs.hyperline.co/api-reference/endpoints/customers/get-customer get /v2/customers/{id} Retrieve the details of an existing customer. # Get customer Source: https://docs.hyperline.co/api-reference/endpoints/customers/get-customer-1 get /v1/customers/{id} We recommend using the `GET /v2/customers/{id}` endpoint instead. # Get customer ARR history Source: https://docs.hyperline.co/api-reference/endpoints/customers/get-customer-arr-history get /v1/customers/{id}/arr-history List the subscription-level ARR evolutions for a customer in reverse chronological order. # Get customer portal Source: https://docs.hyperline.co/api-reference/endpoints/customers/get-customer-portal get /v1/customers/{id}/portal Retrieve the URL of the customer portal. # Get customer tax rates Source: https://docs.hyperline.co/api-reference/endpoints/customers/get-customer-tax-rates get /v1/customers/{id}/taxes/rates Retrieve the eligible tax rates for a customer. # Get customer valuation Source: https://docs.hyperline.co/api-reference/endpoints/customers/get-customer-valuation get /v1/customers/{id}/valuation Compute aggregated valuation metrics across all active subscriptions for a customer. # List customers Source: https://docs.hyperline.co/api-reference/endpoints/customers/list-customers get /v1/customers We recommend using the `GET /v2/customers` endpoint instead. # List customers Source: https://docs.hyperline.co/api-reference/endpoints/customers/list-customers-1 get /v2/customers Retrieve existing customers. # Unarchive customer Source: https://docs.hyperline.co/api-reference/endpoints/customers/unarchive-customer put /v1/customers/{id}/unarchive Unarchive an archived customer. # Update customer Source: https://docs.hyperline.co/api-reference/endpoints/customers/update-customer put /v1/customers/{id} Update the details of an existing customer. # Create export Source: https://docs.hyperline.co/api-reference/endpoints/exports/create-export post /v1/exports Prepare an export of a given type for download. You can check the export readiness status using the GET endpoint. Once the export is ready, download the export using the download endpoint. # Download export Source: https://docs.hyperline.co/api-reference/endpoints/exports/download-export get /v2/exports/{exportId}/download Download the file associated with a specific export, returned as a downloadable file. We recommend enabling redirect following in your HTTP client. # Get export Source: https://docs.hyperline.co/api-reference/endpoints/exports/get-export get /v1/exports/{exportId} Retrieve the details of an existing export. # List exports Source: https://docs.hyperline.co/api-reference/endpoints/exports/list-exports get /v1/exports List previously created exports, most recent first. # Archive feature Source: https://docs.hyperline.co/api-reference/endpoints/features/archive-feature put /v1/features/{code}/archive Archive a feature definition. # Create feature Source: https://docs.hyperline.co/api-reference/endpoints/features/create-feature post /v1/features Create a feature definition. # Delete feature Source: https://docs.hyperline.co/api-reference/endpoints/features/delete-feature delete /v1/features/{code} Delete an archived feature definition that is not in use. # Get feature Source: https://docs.hyperline.co/api-reference/endpoints/features/get-feature get /v1/features/{code} Retrieve a feature definition. # List features Source: https://docs.hyperline.co/api-reference/endpoints/features/list-features get /v1/features List feature definitions. # Unarchive feature Source: https://docs.hyperline.co/api-reference/endpoints/features/unarchive-feature put /v1/features/{code}/unarchive Unarchive a feature definition. # Update feature Source: https://docs.hyperline.co/api-reference/endpoints/features/update-feature put /v1/features/{code} Update a feature definition. # Create file Source: https://docs.hyperline.co/api-reference/endpoints/files/create-file post /v1/files Create a new file. # Delete file Source: https://docs.hyperline.co/api-reference/endpoints/files/delete-file delete /v1/files/{id} Delete an existing file. # Download file Source: https://docs.hyperline.co/api-reference/endpoints/files/download-file get /v1/files/{id}/download Download an existing file content. # List files Source: https://docs.hyperline.co/api-reference/endpoints/files/list-files get /v1/files Retrieve existing files. # Create component token Source: https://docs.hyperline.co/api-reference/endpoints/integrations/create-component-token post /v1/integrations/components/token Create a new token for embedded components. # List invoice events Source: https://docs.hyperline.co/api-reference/endpoints/invoices->-events/list-invoice-events get /v1/invoices/{id}/events Retrieve billable events for an invoice, with per-event pricing computed against the invoice's billing rules. Works for any invoice status: draft and open invoices compute pricing live, finalized invoices serve the snapshot taken at issuance. Per-event amounts are gross — discounts (coupons, percentage, fixed amount) are applied at the line-item or invoice level, not redistributed across events. Use the invoice endpoint to read `discount_amount` if you need the net. # Create transaction Source: https://docs.hyperline.co/api-reference/endpoints/invoices->-transactions/create-transaction post /v1/invoices/{id}/transactions Create a transaction allocated to an existing invoice, rejecting transactions that cannot be allocated and leaving any excess amount unallocated. # Delete transaction Source: https://docs.hyperline.co/api-reference/endpoints/invoices->-transactions/delete-transaction delete /v1/invoices/{id}/transactions/{transactionId} Delete a scheduled transaction or wallet debit linked to an existing invoice. # Charge invoice Source: https://docs.hyperline.co/api-reference/endpoints/invoices/charge-invoice post /v1/invoices/{id}/charge Manually trigger the payment of the invoice. # Create credit note Source: https://docs.hyperline.co/api-reference/endpoints/invoices/create-credit-note post /v1/invoices/{id}/credit-notes Create a credit note for an existing invoice. # Create invoice Source: https://docs.hyperline.co/api-reference/endpoints/invoices/create-invoice post /v1/invoices Create a new invoice. # Create invoices Source: https://docs.hyperline.co/api-reference/endpoints/invoices/create-invoices post /v2/invoices/batch Create invoices async in batch. Results can be tracked via webhooks with the `invoice.batch.creation_succeeded` and `invoice.batch.creation_failed` events. # Delete invoice Source: https://docs.hyperline.co/api-reference/endpoints/invoices/delete-invoice delete /v1/invoices/{id} Delete an invoice in `draft` status or imported from an external source. For other statuses, the `POST /v1/invoices/{id}/void` endpoint must be used. # Download invoice Source: https://docs.hyperline.co/api-reference/endpoints/invoices/download-invoice get /v2/invoices/{id}/download Download the PDF of an existing invoice, returned as a downloadable file. We recommend enabling redirect following in your HTTP client. # Get invoice Source: https://docs.hyperline.co/api-reference/endpoints/invoices/get-invoice get /v1/invoices/{id} We recommend using the `GET /v2/invoices/{id}` endpoint instead. # Get invoice Source: https://docs.hyperline.co/api-reference/endpoints/invoices/get-invoice-1 get /v2/invoices/{id} Retrieve the details of an existing invoice. # List invoices Source: https://docs.hyperline.co/api-reference/endpoints/invoices/list-invoices get /v1/invoices We recommend using the `GET /v2/invoices` endpoint instead. # List invoices Source: https://docs.hyperline.co/api-reference/endpoints/invoices/list-invoices-1 get /v2/invoices Retrieve existing invoices. By default, invoices with status open are not included. # Mark as uncollectible Source: https://docs.hyperline.co/api-reference/endpoints/invoices/mark-as-uncollectible post /v1/invoices/{id}/uncollectible Mark an invoice as uncollectible, useful for keeping track of bad debts that can be written off for accounting purposes. # Send invoice emails Source: https://docs.hyperline.co/api-reference/endpoints/invoices/send-invoice-emails post /v1/invoices/send-email Send a specific email (`email_type`) to the customer for a list of invoices, asynchronously in batch. An invoice whose status doesn't resolve to the requested email is skipped. Results can be tracked via webhooks with the `invoice.batch.email_succeeded`, `invoice.batch.email_skipped` and `invoice.batch.email_failed` events. # Update invoice Source: https://docs.hyperline.co/api-reference/endpoints/invoices/update-invoice patch /v1/invoices/{id} Update an invoice. Draft and grace_period invoices allow full edits; finalized invoices are restricted to metadata (paid: custom_note, purchase_order, custom_properties, additional_display_fields, subscription_id; uncollectible: properties, custom_note, custom_properties, additional_display_fields, subscription_id). # Upload PDF to invoice Source: https://docs.hyperline.co/api-reference/endpoints/invoices/upload-pdf-to-invoice post /v1/invoices/{id}/upload Upload a PDF file to an existing invoice. # Validate draft invoice Source: https://docs.hyperline.co/api-reference/endpoints/invoices/validate-draft-invoice post /v1/invoices/{id}/validate Submit a draft invoice for finalization. Returns `pending_approval` when a matching approval workflow applies; otherwise finalizes it for payment. # Void invoice Source: https://docs.hyperline.co/api-reference/endpoints/invoices/void-invoice post /v1/invoices/{id}/void Void an invoice in a `to_pay` status. This action generates a corresponding credit note. A zero-priced invoice in `paid` status (no amount, discount or tax on any line) can also be voided; no credit note is generated for it. # Create invoicing entity Source: https://docs.hyperline.co/api-reference/endpoints/invoicing-entities/create-invoicing-entity post /v1/invoicing-entities Create a new invoicing entity to send invoices from. # Delete invoicing entity Source: https://docs.hyperline.co/api-reference/endpoints/invoicing-entities/delete-invoicing-entity delete /v1/invoicing-entities/{id} Soft deletes an invoicing entity. This action won't delete the associated invoices. # Get invoicing entity Source: https://docs.hyperline.co/api-reference/endpoints/invoicing-entities/get-invoicing-entity get /v1/invoicing-entities/{id} Retrieve a specific invoicing entity. # List invoicing entities Source: https://docs.hyperline.co/api-reference/endpoints/invoicing-entities/list-invoicing-entities get /v1/invoicing-entities Retrieve existing invoicing entities. # Update invoicing entity Source: https://docs.hyperline.co/api-reference/endpoints/invoicing-entities/update-invoicing-entity put /v1/invoicing-entities/{id} Update an existing invoicing entity. # Get monitoring analysis Source: https://docs.hyperline.co/api-reference/endpoints/monitoring/get-monitoring-analysis get /v1/agents/monitoring/analyses/{id} Retrieve one customer health analysis produced by the monitoring agent. # List monitoring analyses Source: https://docs.hyperline.co/api-reference/endpoints/monitoring/list-monitoring-analyses get /v1/agents/monitoring/analyses Retrieve the customer health analyses produced by the monitoring agent, sorted by `created_at` descending. Filter on `customer_id` with `limit=1` to get the latest health score of a customer. # Authorize Source: https://docs.hyperline.co/api-reference/endpoints/oauth2/authorize get /oauth/authorize Initiates OAuth authorization flow. # Generate tokens Source: https://docs.hyperline.co/api-reference/endpoints/oauth2/generate-tokens post /oauth/tokens Exchange authorization code for access token or refresh an existing token. # Get user info Source: https://docs.hyperline.co/api-reference/endpoints/oauth2/get-user-info get /oauth/userinfo Returns user information for the authenticated access token. # OAuth callback Source: https://docs.hyperline.co/api-reference/endpoints/oauth2/oauth-callback get /oauth/callback Handles the authorization callback and sends the user to the consent page. # Register OAuth client Source: https://docs.hyperline.co/api-reference/endpoints/oauth2/register-oauth-client post /oauth/register Register a dynamic OAuth client per RFC 7591. # Revoke token Source: https://docs.hyperline.co/api-reference/endpoints/oauth2/revoke-token post /oauth/revoke Revoke an access or refresh token. # Get organisation Source: https://docs.hyperline.co/api-reference/endpoints/organisations/get-organisation get /v1/organisations/{id} Retrieve the details of an existing organisation. # List organisations Source: https://docs.hyperline.co/api-reference/endpoints/organisations/list-organisations get /v1/organisations Retrieve organisations with their billing details and child customer IDs. # Patch organisation Source: https://docs.hyperline.co/api-reference/endpoints/organisations/patch-organisation patch /v1/organisations/{id} Update the details of an existing organisation. # Create payment Source: https://docs.hyperline.co/api-reference/endpoints/payments/create-payment post /v1/payments Initiate a new payment (limited to one-time): generate an invoice and charge it directly or with a checkout session # Add products to price book Source: https://docs.hyperline.co/api-reference/endpoints/price-books/add-products-to-price-book post /v1/price-books/{id}/products Add products to a price book by copying their default price configurations. # Create price book Source: https://docs.hyperline.co/api-reference/endpoints/price-books/create-price-book post /v1/price-books Create a new price book. # Delete price book Source: https://docs.hyperline.co/api-reference/endpoints/price-books/delete-price-book delete /v1/price-books/{id} Delete an existing price book. # Get price book Source: https://docs.hyperline.co/api-reference/endpoints/price-books/get-price-book get /v1/price-books/{id} Retrieve the details of an existing price book. # List price books Source: https://docs.hyperline.co/api-reference/endpoints/price-books/list-price-books get /v1/price-books Retrieve existing price books. # Remove product from price book Source: https://docs.hyperline.co/api-reference/endpoints/price-books/remove-product-from-price-book delete /v1/price-books/{id}/products/{productId} Remove a product and its price configurations from a price book. # Update price book Source: https://docs.hyperline.co/api-reference/endpoints/price-books/update-price-book put /v1/price-books/{id} Update the details of an existing price book. # Create price configuration Source: https://docs.hyperline.co/api-reference/endpoints/price-configurations/create-price-configuration post /v1/price-configurations Create a new price configuration on an existing product. # Delete price configuration Source: https://docs.hyperline.co/api-reference/endpoints/price-configurations/delete-price-configuration delete /v1/price-configurations/{id} Delete an existing price configuration. # Get price configuration Source: https://docs.hyperline.co/api-reference/endpoints/price-configurations/get-price-configuration get /v1/price-configurations/{id} Retrieve the details of an existing price configuration. # List price configurations Source: https://docs.hyperline.co/api-reference/endpoints/price-configurations/list-price-configurations get /v1/price-configurations Retrieve existing price configurations. # Update prices Source: https://docs.hyperline.co/api-reference/endpoints/price-configurations/update-prices put /v1/price-configurations/{id}/prices Update prices of an existing price configuration. # Delete product feature Source: https://docs.hyperline.co/api-reference/endpoints/products->-features/delete-product-feature delete /v1/products/{id}/features/{code} Delete a feature value from a product. # List product features Source: https://docs.hyperline.co/api-reference/endpoints/products->-features/list-product-features get /v1/products/{id}/features List feature values assigned to a product. # Set product feature Source: https://docs.hyperline.co/api-reference/endpoints/products->-features/set-product-feature put /v1/products/{id}/features/{code} Set a feature value for a product. # Archive product Source: https://docs.hyperline.co/api-reference/endpoints/products/archive-product put /v1/products/{id}/archive Archive an existing product. # Create product Source: https://docs.hyperline.co/api-reference/endpoints/products/create-product post /v1/products Create a new product. # Delete product Source: https://docs.hyperline.co/api-reference/endpoints/products/delete-product delete /v1/products/{id} Delete an archived product that is not in use. # Get product Source: https://docs.hyperline.co/api-reference/endpoints/products/get-product get /v1/products/{id} Retrieve the details of an existing product. Only the first 50 price configurations are returned, to retrieve all of them use `GET /v1/price-configurations`. # List products Source: https://docs.hyperline.co/api-reference/endpoints/products/list-products get /v1/products Retrieve existing products. # Unarchive product Source: https://docs.hyperline.co/api-reference/endpoints/products/unarchive-product put /v1/products/{id}/unarchive Unarchive an archived product. # Update product Source: https://docs.hyperline.co/api-reference/endpoints/products/update-product put /v1/products/{id} Update the details of an existing product. # Approve quote Source: https://docs.hyperline.co/api-reference/endpoints/quotes->-approvals/approve-quote post /v1/quotes/{id}/approve Approve an existing quote (acting as the account owner). # Get quote approvals Source: https://docs.hyperline.co/api-reference/endpoints/quotes->-approvals/get-quote-approvals get /v1/quotes/{id}/approvals Retrieve quote approvals in newest-first order, currently containing one preview for draft or changes-requested quotes or one execution for other statuses. # Get quote template Source: https://docs.hyperline.co/api-reference/endpoints/quotes->-templates/get-quote-template get /v1/quotes/templates/{id} Retrieve the details of an existing quote template. # List quote templates Source: https://docs.hyperline.co/api-reference/endpoints/quotes->-templates/list-quote-templates get /v1/quotes/templates Retrieve existing quote templates. # Create quote Source: https://docs.hyperline.co/api-reference/endpoints/quotes/create-quote post /v1/quotes Create a new quote. # Download quote Source: https://docs.hyperline.co/api-reference/endpoints/quotes/download-quote get /v1/quotes/{id}/download Download an existing quote. # Download quote file Source: https://docs.hyperline.co/api-reference/endpoints/quotes/download-quote-file get /v1/quotes/{quoteId}/files/{id}/download Download a file (attachment or manually signed file) attached to an existing quote. # Duplicate quote Source: https://docs.hyperline.co/api-reference/endpoints/quotes/duplicate-quote post /v1/quotes/{id}/duplicate Create a draft duplicate of an existing quote. # Finalize quote Source: https://docs.hyperline.co/api-reference/endpoints/quotes/finalize-quote post /v1/quotes/{id}/finalize Finalize a draft quote by submitting it for approval or marking it approved when no approval is required. # Get quote Source: https://docs.hyperline.co/api-reference/endpoints/quotes/get-quote get /v1/quotes/{id} Retrieve the details of an existing quote. # Get quote valuation Source: https://docs.hyperline.co/api-reference/endpoints/quotes/get-quote-valuation get /v1/quotes/{id}/valuation Compute valuation metrics for an existing quote. # List quote signers Source: https://docs.hyperline.co/api-reference/endpoints/quotes/list-quote-signers get /v1/quotes/{id}/signers Retrieve the signature workflow of a quote, step by step, with the signature status of each signer. # List quotes Source: https://docs.hyperline.co/api-reference/endpoints/quotes/list-quotes get /v1/quotes Retrieve existing quotes. # Send quote Source: https://docs.hyperline.co/api-reference/endpoints/quotes/send-quote post /v1/quotes/{id}/send Send an existing quote by email for signature. # Set quote signers Source: https://docs.hyperline.co/api-reference/endpoints/quotes/set-quote-signers put /v1/quotes/{id}/signers Replace the signature workflow of a quote with several signers on the customer side and optional countersigners, signing step by step. # Sign quote Source: https://docs.hyperline.co/api-reference/endpoints/quotes/sign-quote post /v1/quotes/{id}/sign Manually mark the quote as signed externally. Built-in Hyperline signature flow won't be used. # Update quote Source: https://docs.hyperline.co/api-reference/endpoints/quotes/update-quote patch /v1/quotes/{id} Update an existing quote. # Void quote Source: https://docs.hyperline.co/api-reference/endpoints/quotes/void-quote post /v1/quotes/{id}/void Void an existing quote. # Get subscription phase Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions->-phases/get-subscription-phase get /v2/subscriptions/{id}/phases/{phaseId} Retrieve the details of a phase for an existing subscription. # List subscription phases Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions->-phases/list-subscription-phases get /v2/subscriptions/{id}/phases Retrieve the details of the phases for an existing subscription. # Transition subscription to next phase Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions->-phases/transition-subscription-to-next-phase post /v2/subscriptions/{id}/next-phase Update a subscription and transition it to the next available phase. # Create subscription template Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions->-templates/create-subscription-template post /v1/subscriptions/templates Create a new subscription template. # Create subscription template configuration Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions->-templates/create-subscription-template-configuration post /v1/subscriptions/templates/{id}/configurations Add a configuration (currency/country, phases, products, contract terms) to a subscription template. # Delete subscription template Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions->-templates/delete-subscription-template delete /v1/subscriptions/templates/{id} Delete a subscription template. Fails if a quote template depends on it. # Delete subscription template configuration Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions->-templates/delete-subscription-template-configuration delete /v1/subscriptions/templates/{templateId}/configurations/{id} Delete a configuration from a subscription template. # Get subscription template Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions->-templates/get-subscription-template get /v1/subscriptions/templates/{id} Retrieve an existing subscription template with its configurations details. # List subscription templates Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions->-templates/list-subscription-templates get /v1/subscriptions/templates Retrieve existing subscription templates. # Update subscription template Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions->-templates/update-subscription-template patch /v1/subscriptions/templates/{id} Update the name or description of a subscription template. # Update subscription template configuration Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions->-templates/update-subscription-template-configuration put /v1/subscriptions/templates/{templateId}/configurations/{id} Replace an existing configuration for a subscription template. # Cancel subscription transition Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions->-transitions/cancel-subscription-transition post /v2/subscriptions/transitions/{id}/cancel Cancel a scheduled subscription transition. # Create subscription transition Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions->-transitions/create-subscription-transition post /v2/subscriptions/transitions Submit a subscription transition configured from a subscription, plan, or template. A matching workflow returns it pending approval; otherwise it follows the requested schedule. # Get subscription transition Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions->-transitions/get-subscription-transition get /v2/subscriptions/transitions/{id} Retrieve the details of an existing subscription transition. # List subscription transitions Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions->-transitions/list-subscription-transitions get /v2/subscriptions/transitions Retrieve existing subscription transitions. # Preview subscription transition Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions->-transitions/preview-subscription-transition post /v2/subscriptions/transitions/preview Preview all invoices and credit notes emitted by a subscription transition and the next renewal invoice without applying the transition. # Activate subscription Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions/activate-subscription post /v1/subscriptions/{id}/activate Manually start a subscription for the first time. # Cancel subscription Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions/cancel-subscription post /v1/subscriptions/{id}/cancel Cancel an existing subscription, or remove the scheduled reinstatement of a cancelled one (empty body). # Create subscription Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions/create-subscription post /v2/subscriptions Create a new subscription from a plan or manually with products. # Create subscription update Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions/create-subscription-update post /v1/subscriptions/{id}/update Create an update to apply on an existing subscription. # Create subscription updates Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions/create-subscription-updates post /v1/subscriptions/{id}/update-many Create multiple updates to apply at once to an existing subscription. # Get subscription Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions/get-subscription get /v2/subscriptions/{id} Retrieve the details of an existing subscription. # Get subscription ARR history Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions/get-subscription-arr-history get /v1/subscriptions/{id}/arr-history List the ARR evolutions for a subscription in reverse chronological order. # Get subscription valuation Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions/get-subscription-valuation get /v1/subscriptions/{id}/valuation Compute valuation metrics for an existing subscription. # List subscriptions Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions/list-subscriptions get /v2/subscriptions Retrieve existing subscriptions. By default, draft, voided, cancelled and archived subscriptions are not included (`status=all` applies the same exclusion) — pass `status=any` to list every status, or `status__in=active,cancelled` to pick the ones you need. # Pause subscription Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions/pause-subscription post /v1/subscriptions/{id}/pause Pause a subscription. If the subscription is already paused, updates its reactivation date. # Preview subscription timeline Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions/preview-subscription-timeline get /v1/subscriptions/{id}/preview-timeline Preview a subscription's upcoming billing timeline: its future lifecycle events — renewals and phase changes — in chronological order, each with the invoice document(s) it would issue, plus why the projection stopped. Amounts are best-effort estimates (metered usage is assumed to be 0). Pass `starts_at` to preview a subscription that is still pending an activation event (a manual activation, checkout, quote signature, or a manually-started contract); the projection assumes the subscription starts at that instant. # Reactivate subscription Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions/reactivate-subscription post /v1/subscriptions/{id}/reactivate Reactivate a paused subscription. `reactivate_at` may be in the past (after the pause date) or in the future to schedule it; `invoicing_mode` (or `charge_line_items`) controls how the paused gap is invoiced. # Refresh seat products Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions/refresh-seat-products post /v2/subscriptions/{id}/refresh-seat-products Triggers 'count' updates on connected seat products within the subscription. This action will use the dataloader query to retrieve and update the number of units for each seat product. # Refresh subscriptions Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions/refresh-subscriptions post /v1/subscriptions/refresh Triggers refresh of subscriptions usage data and related open invoices. This action is used when the automatic billing update upon ingestion option is disabled for the account. # Reinstate subscription Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions/reinstate-subscription post /v1/subscriptions/{id}/reinstate Reinstate a subscription scheduled for cancellation, or a fully-cancelled one using `reactivate_at` (a future date schedules it) and `invoicing_mode` (or `charge_line_items`) to control how the cancelled gap is invoiced. # Renew subscription Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions/renew-subscription post /v1/subscriptions/{id}/renew This action will move the subscription into the future up to a specific date (exclusive), as if the renewals had occurred. As a result, the corresponding future invoices will be generated. If the subscription is currently pending, this action will activate it. A limit of 36 renewals applies. # Simulate subscription updates Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions/simulate-subscription-updates post /v1/subscriptions/{id}/simulate-updates Simulate the effect of updates on a subscription without actually applying them. # Update subscription Source: https://docs.hyperline.co/api-reference/endpoints/subscriptions/update-subscription put /v2/subscriptions/{id} Update configuration of a subscription including phases and products. # Create tax rate Source: https://docs.hyperline.co/api-reference/endpoints/taxes/create-tax-rate post /v1/taxes/rates Create a custom rate or a code mapping for a default rate. # Delete tax rate Source: https://docs.hyperline.co/api-reference/endpoints/taxes/delete-tax-rate delete /v1/taxes/rates/{id} Delete an existing custom or default tax rate mapping. # Get tax rate Source: https://docs.hyperline.co/api-reference/endpoints/taxes/get-tax-rate get /v1/taxes/rates/{id} Retrieve an existing custom or default tax rate mapping. # List tax rates Source: https://docs.hyperline.co/api-reference/endpoints/taxes/list-tax-rates get /v1/taxes/rates Retrieve existing custom and default tax rate mappings. # Update tax rate Source: https://docs.hyperline.co/api-reference/endpoints/taxes/update-tax-rate patch /v1/taxes/rates/{id} Update an existing custom or default tax rate mapping. # Create app Source: https://docs.hyperline.co/api-reference/endpoints/third-party-apps/create-app post /v1/apps Create a new third-party app. # Delete app Source: https://docs.hyperline.co/api-reference/endpoints/third-party-apps/delete-app delete /v1/apps/{id} Delete an existing third-party app. # List apps Source: https://docs.hyperline.co/api-reference/endpoints/third-party-apps/list-apps get /v1/apps Retrieve existing third-party apps. # Update app Source: https://docs.hyperline.co/api-reference/endpoints/third-party-apps/update-app put /v1/apps/{id} Update an existing third-party app. # Create transaction Source: https://docs.hyperline.co/api-reference/endpoints/transactions/create-transaction post /v1/transactions Record a settled offline payment, refund, or chargeback in the customer's currency without requiring an invoice. # Delete transaction Source: https://docs.hyperline.co/api-reference/endpoints/transactions/delete-transaction delete /v1/transactions/{id} Delete an offline transaction with no invoice allocations, wallet funding, or dependent transactions. # Get transaction Source: https://docs.hyperline.co/api-reference/endpoints/transactions/get-transaction get /v1/transactions/{id} Retrieve the details of an existing transaction. # List transactions Source: https://docs.hyperline.co/api-reference/endpoints/transactions/list-transactions get /v1/transactions Retrieve transactions across all invoices and transactions without an invoice allocation. # Refund transaction Source: https://docs.hyperline.co/api-reference/endpoints/transactions/refund-transaction post /v1/transactions/{id}/refund Refund a settled banking transaction for its full amount. The related invoice will switch back to to pay status. Use the create credit note endpoint if you want to cancel (and optionally refund) the initial invoice. # Get user role Source: https://docs.hyperline.co/api-reference/endpoints/users->-roles/get-user-role get /v1/users/roles/{id} Retrieve the details of an existing user role. # List user roles Source: https://docs.hyperline.co/api-reference/endpoints/users->-roles/list-user-roles get /v1/users/roles Retrieve existing user roles. # Get user Source: https://docs.hyperline.co/api-reference/endpoints/users/get-user get /v1/users/{id} Retrieve the details of an existing user. # List users Source: https://docs.hyperline.co/api-reference/endpoints/users/list-users get /v1/users Retrieve existing users. # Create wallet Source: https://docs.hyperline.co/api-reference/endpoints/wallets/create-wallet post /v1/wallets Create a new wallet. # Get wallet Source: https://docs.hyperline.co/api-reference/endpoints/wallets/get-wallet get /v1/wallets/{id} Retrieve the details of an existing wallet. # Get wallet settings Source: https://docs.hyperline.co/api-reference/endpoints/wallets/get-wallet-settings get /v1/wallets/settings Retrieve the global settings of the wallets. # List wallet transactions Source: https://docs.hyperline.co/api-reference/endpoints/wallets/list-wallet-transactions get /v1/wallets/{id}/transactions Retrieve all transactions of an existing wallet. # List wallets Source: https://docs.hyperline.co/api-reference/endpoints/wallets/list-wallets get /v2/wallets Retrieve existing wallets. # Load wallet Source: https://docs.hyperline.co/api-reference/endpoints/wallets/load-wallet post /v1/wallets/{id}/load Load free credits or paid credits from a paid invoice, an existing transaction, or a new transaction onto a wallet. # Revert wallet load Source: https://docs.hyperline.co/api-reference/endpoints/wallets/revert-wallet-load post /v1/wallets/{id}/transactions/{transactionId}/revert Revert a credit wallet transaction. Voids its related credit note when applicable and creates a debit transaction. # Update wallet Source: https://docs.hyperline.co/api-reference/endpoints/wallets/update-wallet put /v1/wallets/{id} Update the details of an existing wallet. # Update wallet settings Source: https://docs.hyperline.co/api-reference/endpoints/wallets/update-wallet-settings patch /v1/wallets/settings Update the global settings of the wallets. # Create webhook endpoint Source: https://docs.hyperline.co/api-reference/endpoints/webhooks/create-webhook-endpoint post /v1/webhooks/endpoints Create a new webhook endpoint. # Delete webhook endpoint Source: https://docs.hyperline.co/api-reference/endpoints/webhooks/delete-webhook-endpoint delete /v1/webhooks/endpoints/{id} Delete an existing webhook endpoint. # Get webhook endpoint Source: https://docs.hyperline.co/api-reference/endpoints/webhooks/get-webhook-endpoint get /v1/webhooks/endpoints/{id} Retrieve an existing webhook endpoint. # List webhook endpoints Source: https://docs.hyperline.co/api-reference/endpoints/webhooks/list-webhook-endpoints get /v1/webhooks/endpoints Retrieve all webhook endpoints. # List webhook messages Source: https://docs.hyperline.co/api-reference/endpoints/webhooks/list-webhook-messages get /v1/webhooks/messages Retrieve all webhook messages sent. Please note that, by default, this endpoint is limited to retrieving 90 days' worth of data relative to now. Messages that date back more than 90 days are still accessible, but their payloads are expunged. If an iterator is provided, the endpoint retrieves data spanning 90 days before/after the time indicated by the iterator ID. If you require data beyond those time ranges, you will need to explicitly set the before or after parameter as appropriate. # Update webhook endpoint Source: https://docs.hyperline.co/api-reference/endpoints/webhooks/update-webhook-endpoint put /v1/webhooks/endpoints/{id} Update an existing webhook endpoint. # Product updates June, 2025 Source: https://docs.hyperline.co/changelog/2025-06 Hyperline June 2025 release: multi-factor authentication, update subscription phases, cancellation reasons, bundle pricing, ChorusPro auto-transmission. ## Multi-factor authentication (MFA) Hyperline now supports advanced authentication via Multi-Factor Authentication (MFA or 2FA) for our enterprise clients. Supported methods include one-time passwords (OTP), one-time codes via email, and biometric authentication (e.g., Touch ID or passkeys). Once MFA is activated, it will be enforced for all account members at their next login. If a user belongs to multiple accounts, MFA will be required for each. ## Update subscription phases Subscription future phases can now be updated. Additionally, you can add new phases or remove existing ones. This allows you to plan contract changes in advance, such as pricing updates or multi-year configurations. ## Record cancellation reason You can now record the reason for cancelling a subscription. This will be displayed in the subscription details page and accessible from the API. ## New bundle pricing model The bundle pricing model is now available for seat-based products. This allows you to configure predefined bundles with specific quantity/price combinations, making only those options available when creating new quotes and subscriptions. ## Edit footer invoice In addition to the global invoice legal/additional information settings, you can now edit these footer sections of each invoice directly in the invoice editor. This allows for advanced invoice customization to meet ad-hoc needs. ## Switch between B2C and B2B on public pages Public pages (customer portal, checkout, and quote pages) now allow your customers to select between B2C (person) and B2B (corporate) typologies. This selection will determine the required form fields during these flows, and categorize more accurately the customers in Hyperline. ## ChorusPro auto-transmission As part of e-invoicing regulations, Hyperline now supports the automatic transmission of invoices to ChorusPro for Business-to-Government (B2G) customers. Until now, only PDF/XML file generation was available. This new capability removes the need for any manual action on the ChorusPro side by finance teams. # Product updates July, 2025 Source: https://docs.hyperline.co/changelog/2025-07 Hyperline July 2025 release: Apple Pay and Google Pay, expanded filters, customer files API, custom quote file names, external payment method imports. ## Apple Pay / Google Pay Hyperline now supports Apple Pay and Google Pay, enabling frictionless payments and removing the need to manually enter card details. With these methods, customers can also save their card for future use. The payment flow works the same as with credit or debit cards. ## More filters We've added new filters on list pages: * Customers can now be filtered by integration. * Invoices can now be filtered by plan and integration. * Subscriptions can now be filtered by product and coupon. ## Manage customer files via the API You can now list, create, delete, and download customer files through the API. This allows you to programmatically manage files and build advanced use cases for your product on top of Hyperline. ## Custom quote file names The name of a downloaded quote file can now be customized for your account. ## Import external payment methods Payment methods collected outside of Hyperline (for example, via an embedded PSP form in your product) can now be imported into Hyperline using the API. # Product updates August, 2025 Source: https://docs.hyperline.co/changelog/2025-08 Hyperline August 2025 release: edit subscription phases, prefill quantities, preview invoices and quotes, ChartMogul integration, scheduled changes. ## Edit subscription phases You can now add, edit, and delete subscription phases for active subscriptions directly from the subscription update page. This makes it easier to customize phases to better align with each customer or contract's future needs. ## Prefill quantity from plan Plans with seat-based products can now include a preconfigured quantity. When the plan is used to create a subscription, the quantity will be automatically prefilled—no manual input required. ## Preview invoices and quotes We improved the PDF preview of invoices and quotes by clearly highlighting the displayed language. You can now easily switch between the account language (legal) and the customer's language with a single click when both are different. ## Product order in subscriptions The order of products in a subscription can now be adjusted during creation. Simply move products up or down to control the display order, which will be reflected in related quotes and invoices. ## ChartMogul integration [ChartMogul](https://www.chartmogul.com?utm_source=hyperline) now natively supports Hyperline. Benefit from all ChartMogul capabilities to analyze your subscription revenue from your Hyperline data. ## Schedule subscription changes It's now possible to schedule subscription changes for a specific date using the API. This allows you to programmatically plan updates in advance and build more advanced subscription flows. ## Support for Stripe Link Hyperline now supports Stripe Link, a Stripe-specific payment method that can be automatically imported and used to process invoice charges in Hyperline. # Product updates September, 2025 Source: https://docs.hyperline.co/changelog/2025-09 Hyperline September 2025 release: subscription templates, credit auto top-up, relative coupon durations, uncollectible invoices, non-recurring subs. ## Subscription templates We are progressively rolling out a subscription templates module, introducing a new way to preconfigure subscriptions with their full set of options and capabilities. Similar to plans, they allow subscriptions to be assigned in a single click and can be used in quote templates. The key difference from plans is that these templates include all subscription options available in the subscription assignment flow (phases, contracts, advanced options, etc.). This removes existing limitations and moves toward a broader concept of templates. Plans will be gradually discontinued. *Contact our support if you are interested.* ## Auto top-up on credits Customer credit balances can now be automatically topped up, either from an existing catalog price or a custom one. These options are available both in the UI and via the API. ## Relative duration on coupons Coupons within subscriptions can now be configured with a relative duration (e.g., 6 months). You can now set them to apply once, for a fixed duration, or for the entire phase or subscription period. ## Custom quote name Clients can now customize the quote name on the document — for example, renaming “Quote” to “Contract” or removing the quote number displayed. The configuration of this name is available in all supported languages. ## Uncollectible invoice Invoices can now be marked as uncollectible, allowing you to track bad debts that may be written off for accounting purposes. An uncollectible invoice can still be paid by the customer (it remains “to pay”). ## Non-recurring subscriptions Hyperline subscriptions can now contain one-time products only, allowing you to represent customer contracts and terms, or include only credit-based products — all without recurring usage. ## Transition options on quote update When configuring a quote for a subscription update, you now have different options to transition from the current configuration to the new one: * Direct: a new billing cycle starts when the quote is signed, with no transition invoice (no refund from the previous phase and no prorated charge for the new phase). * Pro-rata: the default behavior until now. Billing cycles are preserved when possible, and a transition invoice with prorations is issued at quote signature. This remains the default behavior. ## Transaction synchronization with accounting software When using an integration with accounting software, you now have the flexibility to configure the synchronization direction between Hyperline and your accounting system. ## UI updates We've rolled out several UI improvements: * Added a secondary navigation bar for each product category * Moved audit pages to the main navigation * Added filters to the products page * Updated status iconography for quotes, invoices, and transactions # Product updates October, 2025 Source: https://docs.hyperline.co/changelog/2025-10 Hyperline October 2025 release: transactions page, subscription versions, accounting observability, edit current phase, e-invoicing Spain and Belgium. ## Transactions page We added a brand-new page in Hyperline to track transactions at the account level. This page lists all transactions that occurred in your account, including payments and refunds, providing a clear overview of your cash activity. Filters and export options are also available. ## Subscription versions We introduced subscription versions to help you track changes to your subscriptions over time. Each time a subscription is updated, a new version is created, allowing you to view the full history of changes made to that subscription. ## Accounting integrations observability We improved the observability of our accounting integrations by adding detailed logs in case of issues. This helps you clearly monitor syncs and quickly identify and resolve any problems that may arise. ## Edit current subscription phase Just like with future phases, you can now edit the current phase of a subscription. ## E-invoicing Spain and Belgium Automated e-invoicing transmission is now available for Spain and Belgium. We now send your invoices directly to the tax authorities in these countries, ensuring compliance with local regulations. ## Coupons improvements We made several improvements to the coupons feature. Coupons can now be applied with a relative duration (e.g., for 3 months). You can also select which line items the coupon applies to when creating or editing an invoice in the visual editor. Additionally, you can now create invoices with coupons using the API. ## Bank account error We now send an email to the “Email for technical alerts” address (configured in the email settings) when a connected bank account cannot be refreshed. This proactive notification helps you reconnect your account promptly and ensure invoice reconciliation continues to work seamlessly. ## Update on parent invoices This update applies to organization-based billing. When a parent invoice includes products from a child customer, Hyperline now adds the child customer's name as a prefix to the corresponding product (e.g., ChildCustomerA - Pro Subscription). # Product updates November, 2025 Source: https://docs.hyperline.co/changelog/2025-11 Hyperline November 2025 release: Insights analytics, Attio integration, bank statement reconciliation, quote countersigners, exports API, custom ARR. ## Insights Hyperline now offers a full Insights module that provides a comprehensive overview of your financial and revenue metrics. The **Financial page** includes cash-flow visibility, MRR and debt evolution, aged balances, and complete breakdowns of your revenue and accounts receivable. It also provides detailed MRR analytics including new, expansion, contraction, lost, and net changes. The **Revenue page** provides in-depth insights into your revenue streams, including breakdowns by product, currency, and customer. *This module is in beta. Contact our support if you are interested.* ## Attio integration Hyperline now natively supports [Attio](https://www.attio.com?utm_source=hyperline) CRM. The Hyperline Attio app enables you to create custom quotes or manage subscriptions directly from your Attio deals or companies using pre-built actions. Additionally, the integration can automatically sync your Hyperline quotes, subscriptions, and invoices into Attio as custom objects. [More details in the documentation](../integrations/attio) ## Reconcile from bank statements Automated invoice reconciliation from bank accounts has long been available in Hyperline, including the ability to validate matches from each invoice. Hyperline now also supports reconciliation from bank statements. A dedicated transactions page lists inbound transactions from your connected bank accounts. From there, you can now reconcile invoices with granular manual control and have an overview of all your connected bank account balances. ## Quote countersigner A quote countersigner can now be configured in the settings (first name, last name, and email). When a quote is signed by your customer, if a countersigner is configured, we automatically countersign the quote (i.e. apply an additional signature) before finalizing the full quote signature. ## Exports API You can now [trigger and download exports](../api-reference/endpoints/exports/create-export) of pre-built Hyperline reports (including aged balances, revenue per product/line item/country, line-by-line revenue, etc.) directly from the API. This enables you to automate data extraction from Hyperline for use in your own systems or for further analysis. All report exports now support optional date range filtering via `period_start` and `period_end` parameters, allowing you to extract data for specific time periods. In addition, [customers](../api-reference/endpoints/customers/list-customers), [invoices](../api-reference/endpoints/invoices/list-invoices), [subscriptions](../api-reference/endpoints/subscriptions/list-subscriptions), and [quotes](../api-reference/endpoints/quotes/list-quotes) can also be exported via the API using the list endpoints with advanced filtering options. ## Custom subscription ARR and contract value Hyperline provides automatic calculation of Annual Recurring Revenue (ARR) and contract value for subscriptions out of the box, based on their pricing and billing cycles. However, there are scenarios where you may want to override these automatic calculations. Hyperline now allows you to set custom values for both ARR and contract value on a per-subscription basis, in addition to displaying them in the subscription overview. ## Update subscriptions We've begun rolling out new flows for updating existing subscriptions, offering both simpler and more advanced options. You can now update a subscription using an existing template (or plan) or edit subscription details with enhanced versioning support. This change is the first step in a broader revamp of our subscription update flows, aimed at making them more flexible and easier to use. Upcoming changes include the ability to schedule changes in advance and preview their impact on upcoming invoices. ## Advanced Exact Online settings In Exact Online, a yearly invoice spanning 13 calendar months (e.g., 2025-11-19 to 2026-11-18) is recognized over 13 months instead of 12, resulting in incorrect monthly revenue recognition. Hyperline now supports an advanced setting to adjust this behavior. When this setting is enabled, the invoice period end date for yearly invoices is adjusted (e.g., to 2026-10-31 instead of 2026-11-18) so that revenue is recognized over 12 months. # Product updates December, 2025 Source: https://docs.hyperline.co/changelog/2025-12 Hyperline December 2025 release: scheduled subscription updates, US bank reconciliation, dark mode, wallet auto-load, Insights export, outstanding pay. ## Scheduled subscription updates You can now schedule subscription updates for a future date, allowing you to prepare changes in advance and have them automatically applied at the right time. When preparing the update, preview the impact on upcoming invoices before confirming the changes. ## US bank account reconciliation Automatic reconciliation of bank transactions with invoices has been available for EU countries for a while. We've now extended this capability to US bank accounts. Hyperline connects to over 5,000 banks in the US, automatically matching received transactions with your invoices. We've also added the ability to hide synced transactions you don't need to see, keeping your view clean and focused. ## Dark mode A new dark mode is now available for the Hyperline interface. Whether you prefer a darker aesthetic or want to reduce eye strain during long sessions, you can switch between light and dark themes from your profile settings. ## Credit wallet from credit note When issuing a credit note, you can now credit the corresponding amount directly to the customer's wallet. This balance will automatically apply to their future invoices. ## Wallet auto-load Wallets can now be automatically topped up when the projected balance falls below a defined threshold. Combined with the existing interval-based auto-load, this gives you more flexibility in managing wallet balances. We've also added a new webhook to notify you when a wallet's projected balance drops below the threshold. ## Insights export You can now export data from the Insights module to CSV files. Whether you need to share metrics with your team, build custom reports, or integrate with external tools, all your analytics data is just a click away. ## Process outstanding invoices on payment method update When updating a customer's default payment method, you can now choose to immediately process any outstanding invoices with the new method. Additionally, you can configure the default behavior at your account level to automatically pay (or not) outstanding invoices when customers update their payment method through their portal. # Product updates January, 2026 Source: https://docs.hyperline.co/changelog/2026-01 Hyperline January 2026 release: customer portal authentication, quote approval workflows, expired quote filters, user merge, payment initiation delay. ## Customer portal authentication You can now require customers to authenticate before accessing the customer portal. When enabled, customers must verify their email address through a secure link sent via email before they can view their billing information. This adds an extra layer of security, ensuring only authorized users can access sensitive billing data. Additionally, the link expiration duration is now configurable, allowing you to automatically expire access links after a specified period (in minutes). This reduces the risk of unauthorized access through outdated links. ## Quote approval workflows The quote approval system now supports **advanced approval workflows**, giving sales and finance teams more control over quote validation before it reaches the customer. You can now build **multi-step approval processes** with sequential steps, triggered automatically based on **custom rules** that you can combine with AND/OR logic. *[Learn more about quote approval](../docs/quotes/approval)* ### Slack integration for approval workflows You can now connect Slack to Hyperline and receive approval notifications directly in your channels. When a quote requires approval, the configured Slack channel receives a notification with all relevant context — quote details, customer name, requester, and a direct link to review the quote. Learn more in the [Slack integration documentation](../integrations/slack). ## Filter for expired quotes A new filter is now available on the quotes list to quickly find **expired quotes**. This makes it easier to identify quotes that need attention — whether to follow up with customers or update expiration dates. ## Merge users You can now **merge duplicate users** in your Hyperline account. This is useful when the same team member has been created multiple times — for example, from different CRM integrations. Merging consolidates their activity and permissions into a single profile. ## Custom payment initiation delay per customer The payment initiation delay (grace period between invoice creation and payment collection) can now be configured **at the customer level**, overriding the global setting. This gives you more flexibility to accommodate specific customer agreements or payment terms. # Product updates February, 2026 Source: https://docs.hyperline.co/changelog/2026-02 Hyperline February 2026 release: MCP server, revamped quote-based subscription updates, custom invoice notes, audit log tracking, Insights improvements. ## MCP server The Hyperline MCP server is now generally available. Connect your AI tools to Hyperline using the Model Context Protocol (MCP), with more than 100 tools to interact with your billing data — whether for reporting, analysis, or automation. Learn more about the [MCP server](../api-reference/docs/ai/mcp). ## Subscription update with quotes revamped As part of our subscription update flow revamp, we integrated quotes as a validation step when transitioning to a new subscription. You can now select when the subscription update will take effect, not only starting on quote signature but on any date in the future. This new flow makes the quote for upsell, renewal or modification process simpler and more intuitive, especially when planning future changes. Read more about the way it works on the [dedicated documentation page](/docs/quotes/subscription-update). ## Custom invoice notes in subscriptions You can now define a custom note when configuring a subscription — including from a quote — that will appear on the generated invoices and credit notes. This allows you to add additional context that is automatically carried over to every document. ## Integration tracking in audit logs Audit logs now show which integration performed each action. For example, when a customer is created via your CRM, the log now displays the actual integration instead of a generic "System" label. ## More filters in list pages We added a range of new filters to the customers and subscriptions list pages. You can now filter customers by **tax ID**, **external ID presence**, and **parent or children relationships**. Both customers and subscriptions can be filtered by custom properties, and subscriptions can additionally be filtered by free trial status or draft invoice generation. ## Insights improvements The Insights module has been enhanced with improved visualizations. These include a refined aged balances heatmap with dark-mode support, clearer empty states across charts, and more intuitive navigation in revenue and MRR tables. Chart readability has also been improved with consistent sizing and better axis rendering. # Product updates March, 2026 Source: https://docs.hyperline.co/changelog/2026-03 Hyperline March 2026 release: Slack notifications, Hyperline CLI, French localization, aggregators catalog, multi-aggregator credits, Zoho Books, idempotency. ## Slack notifications You can now configure notification rules in the Slack integration to automatically send messages when specific events occur in Hyperline. Examples include an approval request, an invoice being paid, a quote being signed, or a dataloader error. Slack Notifications Each rule combines a trigger event, a Slack channel, and a message template, giving you full control over what gets notified and where. [*Learn more about Slack notifications*](../integrations/slack) ## Hyperline CLI Hyperline is now available as a [CLI tool](https://www.npmjs.com/package/@hyperline/cli), designed to work seamlessly with AI coding agents like Claude. The CLI provides a lightweight, token-efficient way for agents to interact with your billing data — listing customers, invoices, events, and more using simple terminal commands. Cli Compared to MCP integrations, the CLI avoids context overload and naming conflicts with other tools, resulting in faster and more reliable agent responses, especially on complex multi-step queries. [*Learn more about the Hyperline CLI*](../api-reference/docs/ai/cli) ## Bonjour 🇫🇷 Hyperline is now fully available in French. User language can be changed from the Profile settings. French This completes the existing support for the 8 supported languages (English, French, German, Italian, Spanish, Polish, Portuguese and Dutch) of the customer public pages. ## Aggregators catalog Aggregators for usage-based billing now have their own dedicated section under Usage > Aggregators, separate from the product creation form. You can create, edit, and manage aggregators independently, see which products reference each one, and reuse the same aggregator across multiple products. Usage Aggregators This makes metering configuration easier to maintain as your catalog grows, with a clearer separation between usage tracking and product setup. [*Learn more about aggregators*](../docs/usage/aggregators) ## Multi-aggregator credits Credit products can now be linked to multiple aggregators, allowing different event types to consume different credit amounts from the same balance. This is especially useful when a single credit pool covers several types of usage. Multi Aggregators We also introduced a new chart-based display for credit balances and an improved transactions table with invoice details and an exploration modal. ## Zoho Books integration Hyperline Zoho Books Zoho Books is now supported as an accounting integration, with the same scope as our existing accounting connectors — automatic invoice and credit note synchronization. [*Learn more about the Zoho Books integration*](/integrations/zoho-books) ## Subscription linking on invoices You can now link or unlink subscriptions directly from the invoice creation and editing form, making it easier to associate invoices with the right subscription for reporting purposes. Linked Subscription The invoice form has also been improved with automatic period computation, smarter defaults, and a cleaner layout for payment methods and line items. [*Learn more about invoice management*](../docs/invoices/manage) ## Renewals report Renewals Report A new **Renewals** report is now available in the Insights module, helping you track upcoming and past subscription renewals at a glance. ## API idempotency keys API requests now support idempotency keys, allowing you to safely retry requests without risk of duplicate operations. This is particularly useful for critical actions like invoice creation, and follows a common API standard for reliable integrations. [*Learn more about idempotent requests*](/api-reference/docs/idempotent-requests) ## Quote price tier display Quote Price Tiers When building a quote, you can now configure which price tiers are displayed for each line item: all tiers, only the matching tiers based on quantity, or none. This gives you more control over the level of pricing detail your customers see. # Product updates April, 2026 Source: https://docs.hyperline.co/changelog/2026-04 Hyperline April 2026 release: customer segments, Adyen integration, file summary, minimum invoice fees, multiple checkout payment methods, valuation APIs. ## Customer segments Customer segments let you slice your customer base into dynamic, rule-based groups — for example "Enterprise customers in France paying by direct debit" or "All customers with a parent company". Segments can then be used to filter the customers list or in the Insights module for granular analysis. Customer Segments [*Learn more about customer segments*](../docs/customers/segments) ## Adyen integration Hyperline now supports Adyen as a payment provider to collect payments from your customers. Card, SEPA Direct Debit and Bacs Direct Debit are all supported. Adyen Integration [*Learn more about the Adyen integration*](../integrations/adyen) ## File summary When uploading files to the customer files module, a summary is now automatically generated and displayed so you can understand the content of each file at a glance. File Summary ## Minimum invoice fee behavior You can now configure how the minimum invoice fee is applied on subscription invoices: either **replace** (the previous behavior) or **adjustment** (new). The adjustment option keeps the original line item details and adds an extra minimum fee adjustment line. ## Multiple payment methods on checkout Customers can now select which payment method to use on a checkout, or add a new one. Checkouts were previously limited to a single payment method. Checkout Multi Payment Method ## Draft invoices for one-off quotes Draft invoices can now be generated for one-off quotes, giving you full control before finalizing the invoice after quote signature. In addition, quote value with tax can be displayed for this type of quote with a dedicated new option. ## Improvements to filters on custom properties The filtering group for custom properties has been improved to: * Support all custom property types (text, number, date, etc.) with smart logic for each — for example partial match on text-based properties. * Be easily replicated across pages — now available on Customers and Products in addition to the existing pages. Custom Property Filter ## Parent company details on quotes When a customer has a parent company, the parent's address is now displayed on the quote alongside the customer's details. ## Valuation APIs New endpoints have been added to the API to retrieve the valuation of a customer, quote or subscription. They include pre-computed revenue metrics (contract value, recurring contract value, ARR, etc.) and period-level breakdown granularity. # Product updates May, 2026 Source: https://docs.hyperline.co/changelog/2026-05 Hyperline May 2026 release: Sentinel monitoring, Rillet and NetSuite integrations, portal self-service, invoice custom properties, Insights GA, payouts. ## Sentinel Sentinel is your Hyperline monitoring system. It surfaces actionable tasks when something needs attention across payments, invoicing, subscriptions, quotes, and integrations of your account. Sentinel Tasks are grouped by priority, so you can focus on the issues that matter most and open the relevant list directly from the Sentinel panel. [*Learn more about Sentinel*](../docs/sentinel/overview) ## Rillet integration Hyperline now supports Rillet as an accounting integration. You can push invoices, credit notes, customers, payments, and optionally subscription contracts to Rillet. Rillet integration Each Hyperline invoicing entity can be mapped to a Rillet subsidiary, so accounting configuration follows the entity issuing the invoice. [*Learn more about the Rillet integration*](../integrations/rillet) ## NetSuite integration Hyperline now supports NetSuite as an accounting integration. You can push invoices, credit notes, customers, and payments to NetSuite as native Invoice, Credit Memo, and Customer Payment records. NetSuite integration Each Hyperline invoicing entity maps to a NetSuite subsidiary, with full OneWorld support. You can map products to NetSuite items, resolve income and payment accounts through your accounting rules, and feed Hyperline customer and invoice fields into NetSuite custom fields. [*Learn more about the NetSuite integration*](../integrations/netsuite) ## Customer portal self-service Customers can now view their credit transaction history directly from the customer portal, including top-ups, usage consumption, and expirations. Credit history in the customer portal You can also let customers cancel a subscription from the portal. When enabled in **Settings > Hosted pages**, the cancellation schedules the subscription to end at the end of the current billing period, without immediate refund or proration. Customers can undo the cancellation while the current period is still active. Subscription cancellation from the customer portal [*Learn more about credits*](../docs/credits/overview) ## Invoice custom properties Custom properties can now be created for invoices. Values can be set from the invoice builder or when editing an invoice. Invoice custom properties When the same custom property applies to both subscriptions and invoices, Hyperline automatically copies the subscription value to invoices generated from that subscription. [*Learn more about custom properties*](../docs/properties/overview) ## Insights generally available The **Insights** module is now generally available. It gives you interactive financial and revenue dashboards with drilldowns, detailed tables, and filters. Insights [*Learn more about Insights*](../docs/analytics/insights) ## Payout reconciliation Payout reconciliation is now available directly within Hyperline, making it easier to match payment provider payouts with the related transactions in Hyperline. Only supported for Stripe for now. Stripe payout reconciliation [*Learn more about reconciliation*](../docs/invoices/reconciliations) ## Transaction refunds You can now refund a transaction directly from Hyperline. Use this when money should be returned through the original payment method without creating a credit note. After the refund settles, the invoice may move back to `to pay`, with the original payment and refund both visible as transactions. Transaction refund [*Learn more about refunds*](../docs/invoices/refunds) ## Automated exports Report data can now be exported directly to a Postgres or Snowflake warehouse on a 12-hour or 24-hour schedule. This helps finance and data teams keep reporting tables refreshed without relying on manual exports. Automated exports [*Learn more about reports*](../docs/analytics/reports) ## Bundle products Bundle products let you package several catalog products into a single offering. Each bundle can allocate revenue across its components and control how the bundle appears on invoices. You can display a bundle as one invoice line, or show each component separately when customers need a detailed breakdown. Bundle products [*Learn more about products and prices*](../docs/products/overview) ## Translation overrides You can now edit product names and descriptions at the subscription level, and override invoice line item translations when editing an invoice manually. This gives you more control over the labels shown to multilingual customers without changing the shared catalog product. Translation overrides [*Learn more about subscription translations*](../docs/subscriptions/translations) ## Stricter VAT validation for reverse charge A new tax setting lets you require a valid VAT number before applying reverse charge in the EU. When **Enforce a valid tax number for reverse charge** is enabled, Hyperline applies reverse charge only after the customer's tax number has been validated. Hyperline also stores the VIES consultation number on the customer and invoice. Stricter VAT validation for reverse charge [*Learn more about tax management*](../docs/invoices/tax-management#enforce-a-valid-tax-id-for-reverse-charge) # Product updates June, 2026 Source: https://docs.hyperline.co/changelog/2026-06 Hyperline June 2026 release: customer intelligence, new customer details page, formula-based aggregators, duplicate quotes, saved views, API logs. ## Customer intelligence Hyperline now features a complete **Customer intelligence** module to help you monitor customer health, usage, payment behavior, ownership, and follow-up needs from one place. Customer intelligence Customer intelligence brings together revenue data, billing activity, usage signals, and customer context so teams can identify risks and opportunities earlier. You can use it to track late payment behavior, monitor customer activity, assign owners and followers, and set up monitoring agents for important accounts. [*Learn more about customer intelligence*](../docs/customer-intelligence/overview) This new module is currently in beta and available through private access. Get early access ## New customer details page The customer details page has been redesigned with a clearer layout and more structured information. The page now gives you a better overview of each customer, including billing status, wallet balance, usage activity, subscriptions, invoices, and customer intelligence signals when enabled. New customer details page The customer wallet experience has also been refreshed as part of this update. You can add funds by initiating a prepayment, recording an offline payment received outside Hyperline, or adding free funds. Wallet transactions can include comments for additional context, and you can choose a custom amount when charging an invoice from the wallet. [*Learn more about customer wallets*](../docs/wallets/balance) ## Formula-based usage aggregators Aggregators now support SQL formulas, so you can create usage metrics beyond simple counts and sums. For example, you can bill from an average over a period, keep the highest value reached, cap a billed amount, remove an included allowance, or combine several event values into one metric. An AI helper is also available to help build formulas. [*Learn more about aggregators*](../docs/usage/aggregators) ## Duplicate quote Quotes can now be duplicated in one click. Duplicate quote The duplicated quote is created as a draft and keeps the original quote content, including subscription configuration, invoice configuration, contract clauses, and attachments. This helps teams reuse existing deal structures without rebuilding them from scratch. ## More flexible quote approvals Approval workflows can now use more quote conditions. You can trigger approval when non-default payment terms are applied, when a specific contract clause is used, or when a reusable clause has been edited before the quote is validated. More flexible quote approvals [*Learn more about quote approvals*](../docs/quotes/approval) ## Tax controls Customer tax handling is now more explicit. You can set a customer as taxable or tax-exempt and require tax IDs for company customers per invoicing entity. You can also filter the customer list by tax ID status to identify records that need review. [*Learn more about tax management*](../docs/invoices/tax-management) ## Saved views and list filters Saved views are now available for customers, subscriptions, and invoices. You can save a filtered list view, reuse it later, and set it as the default view for that list. Saved views and list filters The quotes list also now supports filtering by customer. [*Learn more about saved views*](../docs/getting-started/saved-views) ## API activity logs You can now review API activity directly in Hyperline. API activity logs Each log gives you more visibility into requests made to your account, including the request status, source, API key used, and related Hyperline entities. This makes it easier to understand integration behavior without leaving the product. # Product updates July, 2026 Source: https://docs.hyperline.co/changelog/2026-07 Hyperline July 2026 release notes: consolidated invoicing, Customer Intelligence integrations, feature entitlements, Slack quote approvals, and PostHog. ## Consolidated invoicing Customers with several subscriptions can now receive one consolidated invoice per billing day instead of a separate invoice for each subscription. Consolidated invoicing Hyperline automatically combines eligible subscription invoices, while giving you more control over when grouped invoices are generated. When an invoice cannot be grouped, a Sentinel task identifies the affected invoices and links directly to the information you need to resolve the issue. You can also force invoices to remain as drafts for selected customers, making it easier to review consolidated or organization-level invoices before issuing them. [*Learn more about consolidated invoicing*](../docs/invoices/consolidated-invoicing) ## More integrations for Customer Intelligence Customer Intelligence can now combine Hyperline revenue data with context from more CRM, support, email, and call recording platforms. 12 integrations for Customer Intelligence The available integrations include Attio (including Attio Call Recorder), HubSpot, Salesforce, Intercom, Front, Plain, Pylon, Zendesk, Gmail, Google Meet with Gemini, Claap, and Grain. These connections give the customer monitoring agent access to CRM activity, support conversations, emails, meeting summaries, and transcripts. Your teams can use this context to assess customer health, prepare for renewals, and identify risks or expansion opportunities from one place. Customer Intelligence is currently in beta and available through private access. [*Learn more about Customer Intelligence*](../docs/customer-intelligence/overview) ## Feature entitlements Hyperline now includes feature entitlement management, giving you a central place to define the features and access levels included with your products. Feature entitlements Feature entitlements can represent availability, limits, or configuration values. They are granted through the products a customer subscribes to, with the option to create customer-specific grants and overrides when needed. [*Learn more about feature entitlements*](../docs/entitlements/overview) ## Quote approvals with Slack and delegations Approvers can now receive quote approval requests directly in Slack. From the notification, they can review the related quote and either approve it or request changes. Quote approvals with Slack and delegations Approvers can also delegate approval responsibilities to another team member for a defined period, helping approval workflows continue when someone is unavailable. Approval rules can now use the customer's invoicing entity or the subscription template as conditions, giving you more control over which quotes require review and who should approve them. [*Learn more about quote approvals*](../docs/quotes/approval) ## Organization-based usage billing Usage generated by child customers can now be included in a parent customer's metered subscription. Organization-based usage billing You can combine usage by adding activity across all child customers or by using the highest-consuming customer. This supports organizations that manage several accounts or business units under one commercial agreement. [*Learn more about organization-based usage billing*](../docs/subscriptions/metering#include-child-customers-usage) ## Concurrent subscription-update quotes You can now keep several update quotes open for the same subscription. Concurrent subscription-update quotes The first quote signed is applied automatically, while the remaining open quotes are voided to prevent conflicting updates. A dedicated **Quotes** tab on the subscription shows active proposals alongside the complete quote history. ## Bank account assignment Bank accounts can now be assigned using rules based on the invoice currency, customer country, or customer segment. Bank account assignment You can keep one account for all invoices or route payments to different accounts based on these criteria. Hyperline then displays the appropriate bank details on each invoice. [*Learn more about invoicing entity payment methods*](../docs/account/invoicing-entities#payment-methods) ## PostHog usage data Hyperline can now use PostHog and HogQL as a usage data source. PostHog usage data This lets you turn product analytics events into billable usage and connect product activity to metered pricing without building a separate data pipeline. [*Learn more about the PostHog integration*](../docs/usage/posthog) ## Customer balance drill-down You can now open a customer's account balance to understand how it was calculated. Customer balance drill-down The detailed view breaks the balance down into outstanding invoices, available credit notes, and wallet credit. This makes it easier to understand whether a customer owes money, has available credit, or has a fully settled account. For parent organizations, you can also review the aggregated balance across the parent and its child customers. [*Learn more about customer balances*](../docs/customers/balance) # Product updates August, 2026 Source: https://docs.hyperline.co/changelog/2026-08 Hyperline August 2026 release: French e-invoicing, invoice previews, Customer Intelligence integrations, payment allocations, and retroactive changes. ## French e-invoicing French invoicing entities can now send domestic B2B e-invoices through a Plateforme Agréée (PA) directly from Hyperline. You can use Hyperline or connect your Pennylane account as your PA. French e-invoicing Customer pages show the live routing status from the French e-invoicing directory, with tools to find or override a routing address. Eligible invoices are transmitted in Factur-X format, and you can follow their delivery status from Hyperline. French e-invoicing through a PA is currently in beta while the connected French systems complete their rollout. [*Learn more about French e-invoicing with a PA*](../docs/invoices/einvoicing/france-pa) ## Invoice previews You can now preview the first invoice before confirming a subscription and view the next invoice or credit note for an existing subscription. Invoice previews Previews cover regular renewals, phase changes, and scheduled subscription transitions. The next payment date and amount remain consistent across Hyperline, the customer portal, API, and exports. [*Learn more about creating subscriptions*](../docs/subscriptions/create) ## Customer Intelligence integrations Customer Intelligence now connects to Help Scout, Granola, Outlook and Microsoft 365, and Pappers. These sources bring more support conversations, meeting notes, emails, and company data into each customer profile. They complement existing integrations with Attio, HubSpot, Salesforce, Intercom, Front, Plain, Pylon, Zendesk, Gmail, Google Meet with Gemini, Claap, and Grain. New integrations for Customer Intelligence The monitoring agent can use this additional context to assess customer health and identify risks earlier. Existing connections are also easier to authorize and synchronize, with faster updates and improved email search. Customer Intelligence is currently in beta and available through private access. [*Learn more about Customer Intelligence*](../docs/customer-intelligence/overview) ## More configurable invoice Invoice settings are now organized by invoicing entity, with a preview that reflects the entity you are editing. You can add document fields using customer custom properties and review the result before saving. More configurable invoice Invoices also have a clearer layout for discounts and tiered products. A new rendering engine improves formatting across invoices, credit notes, and quotes. You can also customize the reverse-charge statement for each invoicing entity and language. [*Learn more about invoice configuration*](../docs/invoices/configuration) ## Company autocomplete When creating or editing a customer, you can now search official company registries and prefill billing information from the selected company. Autocomplete is available across ten countries (including France, Germany, Spain, the United Kingdom, and the Netherlands), reducing manual entry and helping keep customer details accurate. Company autocomplete ## Manager-based approvals Members can now be managed separately in production and sandbox accounts, so you can invite someone to test mode without granting access to production. You can also assign a manager to each member and filter your team by role, status, or manager. Quote approval workflows can use **Manager of quote owner** as the approver. This routes each quote to the right manager automatically and keeps the workflow up to date when team assignments change. Manager-based approvals [*Learn more about users and permissions*](../docs/account/users-permissions) [*Learn more about quote approvals*](../docs/quotes/approval) ## Payment allocations Hyperline now separates financial movements from the way funds are applied. A transaction records a payment, refund, or chargeback, while an allocation links all or part of that amount to an invoice, credit note, or wallet. You can now use one transaction across several invoices, keep funds unallocated until needed, and move an allocation from one invoice to another. A new **Transactions** tab brings these movements and their history together on the customer page. You can also record payments, refunds, and chargebacks processed outside Hyperline. When charging an invoice, select a customer payment method and collect either the full balance or a custom amount. Payment allocations [*Learn more about payment allocations*](../docs/payments/allocations) ## Required custom properties Custom properties can now be required on customers, products, subscriptions, and invoices. Hyperline prevents a record from being created or saved until the required business information is complete. Required custom properties [*Learn more about required custom properties*](../docs/properties/overview#requiring-a-custom-property-value) ## Retroactive changes Subscriptions can now be cancelled retroactively within the current billing period. You can issue a prorated or custom credit note, or cancel without adjusting the current invoice. Retroactive cancellation Retroactive updates and subscriptions activated with a past start date now generate all documents already due. This makes backdated changes visible and complete without waiting for later renewal runs. [*Learn more about cancelling subscriptions*](../docs/subscriptions/manage#cancel-subscription) [*Learn more about retroactive subscription updates*](../guides/retroactive-subscription-update) # Product updates September, 2026 Source: https://docs.hyperline.co/changelog/2026-09 September 2026 Hyperline updates: renewal price adjustments, invoice approvals, Customer Intelligence in CRM, email settings, and subscription timelines. ## Contract renewal price adjustments You can now configure a percentage increase or decrease to recurring product prices at contract renewal. Contract renewal price adjustment settings Choose whether to apply the adjustment automatically, prepare a draft quote for signature, or create a draft subscription update for review. You can prepare quotes and draft updates a configurable number of days before renewal. Quotes display the adjustment percentage. [*Learn more about renewal price adjustments*](../docs/subscriptions/contracts#renewal-price-adjustments) ## Customer Intelligence in CRM With the Customer Intelligence add-on, you can now review customer health directly in your CRM. The new HubSpot card and Attio widget show the linked customer's latest health score and monitoring summary. This helps you prepare for renewals and identify accounts that need attention without leaving your CRM. Add the **Customer intelligence** card to HubSpot company, contact, or deal records, or the **Customer intelligence** widget to Attio company or deal records. Open the card or widget to review the detailed monitoring analysis when a result is available. [*Learn more about Customer Intelligence*](../docs/customer-intelligence/overview) [*Learn more about the HubSpot card*](../integrations/hubspot#customer-intelligence-card) [*Learn more about the Attio widget*](../integrations/attio#customer-intelligence-widget) ## Future subscription timeline The **Timeline** tab now shows upcoming subscription events alongside past activity. Upcoming events in a subscription timeline You can review future renewals, phase transitions, and scheduled subscription updates, then preview their associated invoices. Contract renewal events also appear in the timeline, making it easier to understand what happens next for each subscription. ## Invoice and credit note approvals Approval workflows now cover invoice and credit note finalization, using the same approval steps and notifications as quotes. Approval workflow for invoice and credit note finalization When you submit a draft document for finalization and it matches an approval rule, it moves to `Pending approval` for review. This gives your finance team control over which documents need approval before they are issued. [*Learn more about approval workflows*](/docs/account/approvals#applicable-flows) ## Email settings and custom sending domains You can now set up a custom sending domain directly in **Settings > Emailing**. Add your domain, follow the displayed verification instructions, and configure the sender name and email address your customers see. Email settings with a custom sending domain The redesigned settings also let you customize the sender and reply-to address independently for each invoicing entity. You can preview email templates in the product and open newly sent emails from the audit log to see exactly what the recipient received. A delivery history shows recorded events, including email openings likely triggered by automated tools. [*Learn more about email settings*](../docs/account/emails) ## Generate future invoices When generating subscription invoices in advance, you can now review the list of invoices and preview each one before confirming. Previewing invoices before generating them You can also select **Group all invoices into one** to combine the generated invoices into a single invoice instead of issuing a separate invoice for each billing period. [*Learn more about generating future invoices*](../docs/subscriptions/manage#generate-future-invoices) ## Cancellation previews When cancelling a subscription, you can now preview the invoice or credit note Hyperline will issue. This lets you review the charges or credits before confirming. Credit note preview during subscription cancellation Cancellation documents now reference the products being charged or credited, giving you and your customer a clearer breakdown of the adjustment. [*Learn more about cancelling subscriptions*](../docs/subscriptions/manage#cancel-subscription) ## Multiple shipping addresses Customers can now have multiple saved shipping addresses. You can choose whether to use the billing address or a separate shipping destination, then assign a specific address to each subscription. This lets you keep one billing address while displaying different shipping destinations on subscription invoices, for example when a customer has several offices. New API endpoints also let you manage customer addresses through your integration. [*Learn more about customer addresses*](../docs/customers/overview#addresses) ## Mobile quote signing Quote signing is easier on mobile, with a **Sign** button that stays visible at the bottom of the screen and improvements to page layout and scrolling. Mobile quote page with a persistent signing button When required customer details are missing, the signing flow clearly prompts the customer to complete them. Once the details are filled in, the customer moves directly to the next step without having to select **Sign** again. [*Learn more about quote signatures*](../docs/quotes/signature) ## Company autocomplete in public pages Company autocomplete is now available on checkout pages, in the customer portal, on public quote forms, and when configuring an invoicing entity. Company autocomplete on a public page You and your customers can select a company and prefill its details in these forms, extending the autocomplete already available when creating or editing a customer. ## Other improvements * **Subscription invoicing permissions:** A dedicated permission now controls advanced invoicing options, helping you keep finance settings consistent across subscriptions. [*Learn more*](../docs/account/users-permissions) Permission for managing subscription invoice settings * **Catalog coupons on invoices:** Select an existing coupon from your catalog when creating a one-off invoice, alongside the option to configure a discount directly. [*Learn more*](../docs/invoices/manage#apply-coupons) Selecting a catalog coupon on an invoice * **Invoice filters:** Filter invoices by custom property values to find the documents you need. Filtering invoices by a custom property * **Pricing across countries:** Apply a price configuration to several countries without repeating the same setup for each one. [*Learn more*](../docs/products/overview#parameters) Applying a price configuration to several countries * **Accounting rules:** Use an invoice type filter to route standard invoices and custom documents to different accounts. [*Learn more*](../docs/accounting/rules) Invoice type filter in an accounting rule * **Anrok product codes:** Select from existing Anrok product codes when configuring a product, instead of entering an identifier manually. # Hyperline CLI Source: https://docs.hyperline.co/developers/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**: You can pipe CLI output, filter it with `jq`, or chain it with other commands. Agents handle these patterns 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. This opens your browser to securely log in with your Hyperline account: ```bash theme={null} hyperline login ``` The CLI stores credentials 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_... ``` You can generate API keys 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. You don't need any additional configuration or tool registration. ## CLI vs. MCP: which should you 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/developers/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). MCP is 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 a 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, including customers, subscriptions, invoices, products, and usage data * **Easy setup**: Connect through OAuth with one-click installation for supported AI tools, or use an API key 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. The client redirects you 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 key instead. You can generate API keys from your workspace [Settings](https://app.hyperline.co/app/settings/api). Some AI clients support OAuth but do not support dynamic client registration. In that case, the client may ask for an OAuth **Client ID** in addition to the MCP server URL. If your client has a **Client ID** or **OAuth client ID** field: 1. Enter the MCP server URL: `https://mcp.hyperline.co/mcp` 2. Use dynamic client registration if the client offers it 3. If dynamic registration is not available, contact the Hyperline team via the in-app chat to get the static OAuth Client ID for your environment Avoid using a shared API key when you need per-user Hyperline permissions. OAuth keeps access tied to the Hyperline user who authorizes the AI client, so existing roles and permissions still apply. ### 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. Go 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. Click **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 key for direct authentication instead. Once connected, your AI client is authenticated and can access 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. They also cover actions like creating and voiding invoices, generating quotes, assigning subscriptions, querying usage data, and accessing revenue metrics. Once connected, your AI assistant automatically discovers all available tools. Describe what you need in natural language, and the assistant uses the right tools to get it done. ## Sample prompts ### Customer and 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 and 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 and 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 your 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). When you use an API key, they depend on its 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](/developers/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 If you need additional support, contact the Hyperline team via the in-app chat. # Build with LLMs Source: https://docs.hyperline.co/developers/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 Hyperline 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. Hyperline automatically hosts 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. Hyperline automatically hosts 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 the Hyperline documentation MCP server, AI tools can search Hyperline docs during response generation. This provides more accurate answers than generic web searches. Connect your AI tools to the documentation MCP server at `https://docs.hyperline.co/mcp`: 1. Go to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings 2. Click **Add custom connector** 3. Add the server name (e.g., `hyperline-docs`) and URL: `https://docs.hyperline.co/mcp` 4. Click **Add** 5. When using Claude, click 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. Click **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. This makes 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/developers/amount Understand how Hyperline represents monetary values in the API: currency, integer amounts in minor units, and rounding rules across endpoints. Learn about [currency settings](/docs/account/settings#currencies) in Hyperline. The Hyperline API always represents currencies using their **three-letter ISO 4217 code** (see a complete list [here](https://en.wikipedia.org/wiki/ISO_4217#Active_codes_\(List_One\))). It accepts and returns integer amounts in the **currency's smallest unit**. For **European currencies**, this means that Hyperline represents amounts in **cents**. To convert an amount with decimals into its Hyperline format, multiply it by `100`. For example, Hyperline represents an amount of €`34.17` (Euro, a two-decimal currency) 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, Hyperline represents an amount of `F CFA 12065` (West African CFA franc, a zero-decimal currency) as `12065`. # Authentication Source: https://docs.hyperline.co/developers/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 authorize calls. API keys are associated with a single Hyperline account. An access token represents delegated access to a specific account (used for [third-party apps](./third-party-app)). You can have more than one token or key at any point in time. These tokens can authenticate to Hyperline and perform actions on your account. Keep them as safe as you would a password. ## Manage API keys ### Generate an API key An **API key** allows you to use Hyperline's API or integrations such as Zapier. As a Hyperline admin: 1. Go to your workspace [Settings](https://app.hyperline.co/app/settings/api), section API 2. Click **+ New API key** 3. Add a name for this key, and select the appropriate scopes (in most cases you'll need read/write access) 4. Copy the key and store it in a safe space. You won't be able to see it later in Hyperline Hyperline prefixes API keys with either `prod_` or `test_` so you can easily identify and distinguish them between environments. ### Use an authentication token You must provide an API key or access token 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 ``` Hyperline also supports HTTP Basic Authentication, where the `username` is the API key and the `password` is left blank. Use Bearer Authentication instead because it's simpler to debug. ### Keep your data safe Treat your API keys as **highly sensitive information**. Think of a token like a password. You should only give tokens to services you fully trust. Anyone who obtains a leaked token could use it maliciously. A leaked token can give someone access to all of your Hyperline data. If you suspect a token has been compromised, revoke it and replace it with a new one. Never share tokens 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 the `…` icon on the line of the key name, then **Delete** to permanently delete it. You can't recover a deleted key. # Dates & timezones Source: https://docs.hyperline.co/developers/dates-and-timezones Understand how Hyperline represents dates, datetimes, and timezones across the API: ISO 8601 formatting, UTC defaults, and billing-cycle conventions. The Hyperline API handles all dates in UTC (Coordinated Universal Time). When sending dates to the API, you must convert your local timezone dates to UTC. Similarly, the API returns all dates in UTC. ## 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 For example, to create a subscription that starts at midnight (00:00) in Paris timezone (Europe/Paris), send the following UTC values: ```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/developers/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 You exceeded the request rate limit. See [Rate limiting](./rate-limiting) for more details. ## Getting help If you encounter an error that you cannot resolve: 1. Check the error message for guidance 2. Verify your request format and parameters 3. Ensure your authentication credentials are valid 4. Contact the Hyperline team via the in-app chat with the error details and request information # Hyperline for developers Source: https://docs.hyperline.co/developers/getting-started Build billing integrations with the Hyperline API, manage operations with the CLI, and connect AI assistants through MCP. Use the REST API to manage billing data, webhooks to keep your application in sync, and embedded components to give customers access to their billing information. The API uses HTTPS and JSON, with Bearer token authentication. Create a sandbox API key and send your first authenticated request. Review endpoints, request parameters, and responses, starting with customers. Manage customers, subscriptions, and invoices from your terminal or with an AI coding agent. Connect AI assistants to your Hyperline account to query billing data and perform actions. React to billing events and handle delivery, retries, and signature verification. Give your AI tools access to Hyperline documentation through structured files and the documentation MCP server. ## Service endpoints Use the base URL and API key for the same environment: `test_` keys for sandbox and `prod_` keys for production. ### 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) | ## OpenAPI specification Download the [OpenAPI specification](https://api.hyperline.co/openapi) to generate client libraries or import the API into your testing tools. For workflows you can configure in the Hyperline application, see the [product documentation](/docs). If you need help with your integration, contact the team via the in-app chat. # Idempotent requests Source: https://docs.hyperline.co/developers/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 Hyperline accepts idempotency keys on all mutating endpoints (`POST`, `PUT`, `PATCH`) and ignores them on `GET` requests, since those are already safe to retry. # Pagination and filtering Source: https://docs.hyperline.co/developers/pagination Paginate and filter Hyperline API list endpoints with cursor-based pagination, page sizes, and per-endpoint filter parameters for efficient queries. You can paginate and filter all list requests using the same query format. All *list-based* endpoints return data with the same structure. ## Pagination The API uses two parameters for pagination: * `take` is the number of items the API returns. The default is **50** and the max is **100**. * `skip` is the number of items the API skips. The 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 always returns a similarly shaped payload containing: * `data` the items you requested * `meta` the contextual information (total number of items, number selected...) For example, 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 The API offers many filtering capabilities. Pass filters as query parameters using a common pattern. `fieldName__operator=value` For example: * `GET /v1/customers?name__contains=instagram` returns all customers with the name containing instagram * `GET /v1/customers?id__in=123,456,789` returns customers with ID equal to 123, 456, or 789 ## List of available operators * `equals` (or just `=xxx`) * `not` * `lt` * `lte` * `gt` * `gte` * `contains` * `startsWith` * `endsWith` * `in` * `notIn` * `isNull` * `isNotNull` You can apply numerical operators to numbers or dates. You can't filter on every field. Refer to each model in the API reference to see which ones are available. # Rate limiting Source: https://docs.hyperline.co/developers/rate-limiting Understand Hyperline API rate limits, response headers, and best practices to handle 429 responses with retries and exponential backoff strategies. The Hyperline API implements rate limiting to ensure fair usage and protect the platform from abuse. This page details the 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 returns a **429 Too Many Requests** HTTP status code. The response body is: ```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. **Cache responses**: When appropriate, cache responses 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, contact the Hyperline team via the in-app chat. The team works with you to establish appropriate limits based on your use case. # React components Source: https://docs.hyperline.co/developers/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: * Display a customer's subscriptions * Preview and update the payment method * List and download invoices * List and update billing information This page 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 Install the `@hyperline/react-components` NPM package. ```sh Install the package theme={null} npm install @hyperline/react-components ``` To allow a customer to see their Hyperline data, you need to generate a unique authentication token on your server side. You can use the Hyperline 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 accesses 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 subscription 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, provide an `options` prop with the following parameters: | Name | Description | Type | Default value | Required | | - | - | - | - | - | | token | The token specific to your customer | string | | ☑️ | | mode | The Hyperline environment you are using | production \| sandbox | production | | | appearance | Customize 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 Use variables to customize 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 customize 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, see 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} ``` # Third-party app Source: https://docs.hyperline.co/developers/third-party-app Build a third-party app that connects to multiple Hyperline accounts via OAuth, with scoped permissions and secure token-based authorization. Hyperline supports the creation of external integrations, so your product can connect with any Hyperline account. This capability allows external apps to build use-cases such as: * Automating or white-labeling billing-specific needs * Allowing your app to view the data of a Hyperline account * Enabling your app to manage the customer base of a Hyperline account * Allowing your app to manage the product catalog of a Hyperline account * Allowing your app to manage recurring subscriptions or one-time payments of a Hyperline account * Fetching invoices from a Hyperline account This list is non-exhaustive, and you can build a variety of flows with this kind of app. ## Getting started Hyperline uses the **OAuth** standard to allow your app to access data from a connected account with the user's consent. This prevents having to manually exchange API keys. For example, with the user's consent, using OAuth you can call the subscription API on behalf of your user to create a Hyperline subscription. The Hyperline API supports the Authorization Code Grant flow ([RFC 6749 section 4.1](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1)). This flow allows your application to get separate access tokens for each connected Hyperline account. Use a well-established library for making OAuth requests. See the [OAuth library recommendations](https://oauth.net/code/). ## Registering your app ### Prerequisites Hyperline enables third-party app creation manually. Contact the Hyperline team via the in-app chat to enable it. ### Creating an app The first thing you need to do is [create a new app](/api-reference/endpoints/third-party-apps/create-app) using the Apps API. You receive a Client ID and Client Secret. Keep both of them secret. You can use these credentials to: 1. Redirect users to your app's authorization form (Client ID) 2. Exchange auth codes for access tokens (Client ID & Client Secret) 3. Renew your access tokens 4. Deauthorize users from your app (Client ID & Client Secret) Use the create new app API, including the following attributes in a JSON body: * `name`: displayed to the user during the authorization flow * `description` (optional): to show more details to the user * `logo_uri` (optional): to customize the authorization screen with your brand * `callbacks`: URLs whitelisted to use as a callback/redirect after authorization (e.g. a URL within your app that processes authorizations) For now, you can only manage apps (list, update, delete) using the Hyperline API. ## OAuth flow To initiate the flow, you need to direct your user to [`https://api.hyperline.co/v1/oauth/authorize`](/api-reference/endpoints/oauth2/authorize) (or `https://sandbox.api.hyperline.co/v1/oauth/authorize`). You must append these four query parameters to the URL: * `client_id`: received upon app registration * `redirect_uri`: where Hyperline sends the user after authorization. It must match the URL you set when registering your app * `response_type=code`: the only supported mode at the moment * `state`: a random string to prevent CSRF attacks that you verify when the user returns to your app ([more information](https://auth0.com/docs/secure/attack-protection/state-parameters)) This endpoint redirects the user to the Hyperline login page. After authorization, Hyperline redirects the user to your `redirect_uri` with the `code` and `state` query parameters. You must ensure that the query parameter `state` matches the original state you passed at the start of the flow. If it does, you can exchange the provided code for tokens by making a POST request to [`https://api.hyperline.co/v1/oauth/tokens`](/api-reference/endpoints/oauth2/generate-tokens) (`https://sandbox.api.hyperline.co/v1/oauth/tokens`), including the following attributes in a JSON body: * `client_id`: as above * `client_secret`: received upon app registration * `grant_type: "authorization_code"` * `code`: as provided in the query parameters * `redirect_uri`: must match the value set at the `1. Authorize` step You'll then receive tokens in the JSON body: ```json Response JSON body theme={null} { "access_token": "", "refresh_token": "", "expires_in": 3600, "token_type": "bearer" } ``` You must provide access tokens with every API call, specified in the `Authorization` header after a Bearer prefix. For example: ```sh API call using cURL theme={null} curl -H "Authorization: Bearer " https://api.hyperline.co/v1/customers ``` ### Token expiration Access tokens are time-limited. You need to refresh them periodically using the refresh token. The time limits are: * Access token: 24h * Refresh token: does not expire automatically (can be revoked) You can use the `expires_in` field to know the number of seconds left before the app access token expires. Be sure to renew it before this reaches zero. ## Managing tokens ### Refresh a token To renew an access token, make a POST request to [`https://api.hyperline.co/v1/oauth/tokens`](/api-reference/endpoints/oauth2/generate-tokens) (or `https://sandbox.api.hyperline.co/v1/oauth/tokens`), including the following attributes in a JSON body: * `client_id`: received upon app registration * `client_secret`: received upon app registration * `grant_type: "refresh_token"` * `refresh_token`: received during the first authorization flow ### Revoke a token Once issued, you can't revoke access tokens in the same way as cookies with session IDs for server-side sessions. As a result, you should refresh tokens periodically if the user remains active. You can revoke refresh tokens in case they become compromised. Make a POST request to [`https://api.hyperline.co/v1/oauth/revoke`](/api-reference/endpoints/oauth2/revoke-token) (or `https://sandbox.api.hyperline.co/v1/oauth/revoke`), including the following attributes in a JSON body: * `client_id`: received upon app registration * `client_secret`: received upon app registration * `token`: refresh token you want to revoke ## Multiple accounts Learn about [multiple accounts](/docs/getting-started/sandbox#multiple-accounts) on Hyperline. Each access token grants access to all companies associated with the user. To retrieve a list of all user-accessible companies, use the [`https://api.hyperline.co/v1/companies`](/api-reference/endpoints/companies/list-companies) endpoint. To target a specific company, include the `Hyperline-CompanyId` header in each API request. If a user has access to multiple companies and you don't specify the `Hyperline-CompanyId` header, Hyperline uses the first company (oldest one) linked to the user. Include this header by default when constructing a third-party app/flow. # API upgrades Source: https://docs.hyperline.co/developers/upgrades Track Hyperline API changes, deprecations, and upgrades. See what's changed across versions and plan migrations for breaking changes safely. ## October 13, 2026 * Added `requester_comment` on `/v1/quotes/{id}/finalize` POST endpoint * Added `QuoteApproval.request.requester_comment` on `/v1/quotes/{id}/approvals` GET endpoint * Added `coupons[].discount_percent` overrides on `/v1/invoices` POST and `/v1/invoices/{id}` PATCH endpoints * Added `invoice.coupons[].discount_percent` overrides on `/v1/quotes` POST and `/v1/quotes/{id}` PATCH endpoints ## October 12, 2026 * Added subscription ID matching on `search` on `/v1/accounting/revrec/waterfall` GET and `/v1/accounting/revrec/waterfall/cell` GET endpoints * Changed `columns` to list every recognition month, gaps included, on `/v1/accounting/revrec/waterfall` GET endpoint * Changed `rows[].by_month` and `totals.by_month` to hold every month in `columns` on `/v1/accounting/revrec/waterfall` GET endpoint * Changed Waterfall sheet columns to match `/v1/accounting/revrec/waterfall` GET on `/v1/accounting/revrec/waterfall/export` POST endpoint ## October 10, 2026 * Added inline percent coupons (`discount_percent` without `coupon_id`) on `coupons` for `/v1/invoices` POST, `/v1/invoices/{id}` PATCH, `/v1/quotes` POST, `/v1/quotes/{id}` PATCH (one-off quote `invoice`), `/v1/simulate/invoices` POST and `/v1/simulate/quotes` POST endpoints ## October 9, 2026 * Added `/v1/quotes/{id}/approvals` GET endpoint * Added `/v1/customers/{id}/credits/{productId}/portal-settings` GET, PUT endpoints * Added `/v1/agents/monitoring/analyses` GET endpoint * Added `/v1/agents/monitoring/analyses/{id}` GET endpoint * Added scheduled reinstatement support on `/v1/subscriptions/{id}/reinstate` POST endpoint * Added scheduled reinstatement removal on `/v1/subscriptions/{id}/cancel` POST endpoint * Made product-level `price` and `prices` optional on `/v1/subscriptions/templates/{id}/configurations` POST and `/v1/subscriptions/templates/{templateId}/configurations/{id}` PUT endpoints ## October 8, 2026 * Added `/v1/quotes/{id}/signers` GET, PUT endpoints * Made `email` optional on `/v1/quotes/{id}/send` POST endpoint for quotes with signers ## October 7, 2026 * Added `cancelled` subscriptions support on `/v1/subscriptions/{id}/reinstate` POST endpoint * Added `reactivate_at` and `invoicing_mode` on `/v1/subscriptions/{id}/reinstate` POST endpoint ## October 6, 2026 * Added `email` option on custom property `type` fields on `/v1/custom-properties` GET, POST and `/v1/custom-properties/{id}` PUT endpoints * Major * Removed `accounting_software` node from `/v1/accounting/rules/tree` GET endpoint * Made `category` immutable on `/v1/accounting/rules/{id}` PUT endpoint * Removed automatic refund without `trigger_refund` on `/v1/invoices/{id}/credit-notes` POST endpoint ## October 5, 2026 * Added `custom_property_filters` on `/v1/accounting/rules` GET, POST and `/v1/accounting/rules/{id}` GET, PUT endpoints * Added `filters.custom_property_filters` on `/v1/accounting/rules/defaults` POST endpoint * Added `custom_properties` on `/v1/accounting/rules/resolve` POST endpoint * Added `telemetry_managed` option on error response `code` fields on `/v1/ai/billing/check` POST, `/v1/ai/billing/consume` POST and `/v1/ai/billing/snapshot` GET endpoints ## October 2, 2026 * Added `issuing_method` with `manual` and `scheduled` options on `/v1/invoices` POST and `/v1/invoices/{id}` PATCH endpoints and invoice responses * Added `emitted_at` on `/v1/invoices/{id}` PATCH endpoint ## September 30, 2026 * Added `QuoteTemplate.post_signature_activation_enabled` on `/v1/quotes/templates` GET and `/v1/quotes/templates/{id}` GET endpoints ## September 29, 2026 * Added `invoice.subscription_id` on `/v1/quotes` POST and `/v1/quotes/{id}` PATCH endpoints * Added `Quote.subscription_id` on one-off quote responses on `/v1/quotes` GET and `/v1/quotes/{id}` GET endpoints * Added `portal_top_up_auto_activation_enabled` on credit products on `/v1/products` POST endpoint and product responses * Documented `topup`, `usage` and `expiration` options on `type` for `/v1/customers/{id}/credits/{productId}/transactions` GET endpoint ## September 28, 2026 * Added `CustomProperty.default_value` on `/v1/custom-properties` GET, POST and `/v1/custom-properties/{id}` PUT endpoints ## September 17, 2026 * Added `/v1/ai/billing/check` POST endpoint * Added `/v1/ai/billing/consume` POST endpoint * Added `/v1/ai/billing/snapshot` GET endpoint * Added `/v1/ai/calls` POST endpoint * Added `/v1/ai/billing/plans` GET, POST endpoints * Added `/v1/ai/billing/plans/{id}` GET, PUT, DELETE endpoints * Added `/v1/ai/billing/plans/default` GET, PUT, DELETE endpoints * Added `/v1/ai/billing/rate-cards` GET, POST endpoints * Added `/v1/ai/billing/rate-cards/{id}` GET, PUT, DELETE endpoints * Added `/v1/ai/billing/costs` GET endpoint * Added `/v1/ai/billing/costs/items` POST endpoint * Added `/v1/ai/billing/costs/items/{id}` PUT, DELETE endpoints * Added `/v1/ai/billing/costs/overrides` PUT endpoint * Added `/v1/ai/billing/costs/overrides/{id}` DELETE endpoint * Added `/v1/ai/billing/customers/{id}/policies` GET endpoint * Added `/v1/ai/billing/customers/{id}/policies/default` GET, PUT, DELETE endpoints * Added `/v1/ai/billing/customers/{id}/policies/agents/{agent_slug}` GET, PUT, DELETE endpoints * Added `/v1/ai/billing/customers/{id}/apply-default-plan` POST endpoint * Added `/v1/ai/billing/customers/{id}/balance` GET endpoint * Added `/v1/ai/billing/customers/{id}/windows/reset` POST endpoint * Added `/v1/ai/billing/customers/{id}/consumption` GET endpoint * Added `/v1/ai/billing/products/{id}/rate-card` GET, PUT, DELETE endpoints ## September 16, 2026 * Added `modjo` option on integration `provider_name` fields ## September 15, 2026 * Added `Subscription.shipping_address_id` on `/v2/subscriptions` GET, POST and `/v2/subscriptions/{id}` GET, PUT endpoints * Added `subscription.shipping_address_id` on `/v1/quotes` POST and `/v1/quotes/{id}` PATCH endpoints * Added `target_subscription.shipping_address_id` on `/v2/subscriptions/transitions` POST and `/v2/subscriptions/transitions/preview` POST endpoints * Made `address_id` optional on `/v1/customers/{customerId}/shipping` PUT endpoint * Added `credits_balance_auto_creation_enabled` on credit products on `/v1/products` GET, POST and `/v1/products/{id}` GET endpoints * Added product-level `credits_balance_auto_creation_enabled` on `/v2/subscriptions` GET, POST, `/v2/subscriptions/{id}` GET, PUT, `/v1/quotes` POST, and `/v1/quotes/{id}` PATCH endpoints * Added product-level `credits_balance_auto_creation_enabled` on `/v1/subscriptions/templates/{id}/configurations` POST, `/v1/subscriptions/templates/{templateId}/configurations/{id}` PUT, `/v2/subscriptions/transitions` POST, `/v2/subscriptions/transitions/preview` POST, `/v1/simulate/subscriptions` POST, and `/v1/simulate/quotes` POST endpoints * Added `/v1/customers/{customerId}/addresses` GET, POST endpoints * Added `/v1/customers/{customerId}/addresses/{addressId}` PATCH, DELETE endpoints * Added `/v1/customers/{customerId}/shipping` GET, PUT endpoints * Added `/v1/organisations` GET endpoint * Added `Organisation.updated_at` on `/v1/organisations` GET and `/v1/organisations/{id}` GET, PATCH endpoints * Added `filters.invoice_types` on `/v1/accounting/rules/defaults` POST endpoint and `invoice_type` on `/v1/accounting/rules/resolve` POST endpoint, with `invoice` and `document` options ## September 11, 2026 * Added support for `null` values on `committed_count`, `last_usage_billed`, `min_amount`, and `max_amount` in product update payloads on `/v1/subscriptions/{id}/update` POST, `/v1/subscriptions/{id}/update-many` POST, and `/v1/subscriptions/{id}/simulate-updates` POST endpoints ## September 10, 2026 * Added `Customer.force_invoice_draft` on `/v1/customers` GET, POST, `/v1/customers/{id}` GET, PUT, `/v1/customers/batch` POST, and `/v2/customers` GET endpoints ## September 9, 2026 * Added `/v1/transactions` POST endpoint to record a settled offline payment, refund, or chargeback without an invoice * Added `/v1/transactions/{id}` DELETE endpoint to delete an offline transaction with no invoice allocations, wallet funding, or dependent transactions * Documented the `400` response when a transaction cannot be allocated on `/v1/invoices/{id}/transactions` POST endpoint ## September 8, 2026 * Added `Invoice.customer.registration_number` and `Invoice.seller.registration_number` to invoice responses * Added `lt` (Lithuanian) to customer and invoicing entity language options, customer segment language conditions, and invoice download language options * Added support for Lithuanian locales on `/v1/quotes/{id}/download` GET and `/v2/invoices/{id}/download` GET endpoints ## September 7, 2026 * Added `/v1/subscriptions/{id}/preview-timeline` GET endpoint to preview upcoming subscription lifecycle events and estimated invoices * Added `catalog_version_id` on `/v1/quotes` POST and `/v1/quotes/{id}` PATCH endpoints to price a quote from a published catalog version * Added product-level `catalog_version_id` when creating subscriptions, creating or updating quotes and subscription template configurations, and creating or previewing subscription transitions. A product-level catalog version takes precedence over the quote-level version. Explicit `price` or `prices` values take precedence over the catalog version. ## September 3, 2026 * Added `settleable` option on `status` and `status__in` for `/v1/invoices` GET and `/v2/invoices` GET endpoints * Deprecation warning * Marked `Subscription.renew_automatically` and `Subscription.renew_for` as deprecated. Use `Subscription.contract_terms` instead. ## September 2, 2026 * Made `coupons[].name` optional for inline coupons on `/v1/invoices` POST, `/v1/invoices/{id}` PATCH, `/v1/quotes` POST, and `/v1/quotes/{id}` PATCH endpoints. When provided, coupon names must contain at least one character. ## September 1, 2026 * Added `countries` to price configurations on product and price configuration endpoints. Omit this field or send `null` when creating a price configuration to make it eligible in every country. Use an empty array to restrict it to customers with no country set. * Added `scope` with `all`, `domestic`, `intra_eu`, and `international` options for default tax rate mappings on `/v1/taxes/rates` GET, POST and `/v1/taxes/rates/{id}` GET, PATCH endpoints * Clarified that omitting phase `billing_cycle_alignment` at creation uses your account subscription settings. Set `anniversary` or `calendar_period` explicitly when you need a specific alignment. * Documented the `400` response when a provider mapping cannot be updated on `/v1/customers/providers-bulk-update` POST endpoint * Deprecation warning * Deprecated price configuration `country` in favor of `countries`. Use the array to represent all eligible countries. The legacy field cannot distinguish multiple countries from unrestricted eligibility. ## August 31, 2026 * Added `rillet` option on integration `provider_name` fields and `Product.accounting[].integrations.rillet` on product endpoints * Added a `202` response on `/v2/subscriptions/{id}` PUT endpoint when a subscription update is submitted for approval ## August 28, 2026 * Added `jiminny` option on integration `provider_name` fields * Added `invoice` and `credit_note` options on `applicable_flows` for `/v1/approvals/workflows` GET, POST and `/v1/approvals/workflows/{id}` GET, PUT endpoints * Added `pending_approval` and `changes_requested` invoice and subscription transition statuses, including `status` and `status__in` filters on `/v1/invoices` GET, `/v2/invoices` GET, and `/v2/subscriptions/transitions` GET endpoints ## August 27, 2026 * Added `catalog_version_id` to subscription products to identify the published catalog version their prices were copied from * Added `Product.accounting[].integrations.anrok` on product endpoints ## August 26, 2026 * Added `any` option on `status` and `status__in` for `/v2/subscriptions` GET endpoint to include every subscription status * Added `payment_method_type` approval condition field on `/v1/approvals/workflows` GET, POST and `/v1/approvals/workflows/{id}` GET, PUT endpoints ## August 22, 2026 * Added `rillet` option on `provider_name` for `/v1/customers/providers-bulk-update` POST endpoint ## August 21, 2026 * Added support for loading paid wallet credits from an existing payment transaction with `transaction_id` on `/v1/wallets/{id}/load` POST endpoint * Added `date` when recording a new payment transaction on `/v1/wallets/{id}/load` POST endpoint * Added `finalized` option on `status` and `status__in` for `/v1/invoices` GET and `/v2/invoices` GET endpoints * Added `AccountingJournalEntryLine.customer_id` and `AccountingJournalEntryLine.customer_name` on `/v1/accounting/journal-entries` GET, POST, `/v1/accounting/journal-entries/{id}` GET, and `/v1/accounting/journal-entry-lines` GET endpoints ## August 20, 2026 * Added `granola` option on integration `provider_name` fields * Added `amount` on `/v1/invoices/{id}/charge` POST endpoint to support partial charges * Added `credit_note_ready` option on `email_type` for `/v1/invoices/send-email` POST endpoint ## August 19, 2026 * Added `/v1/transactions` GET endpoint * Added `/v1/transactions/{id}` GET endpoint ## August 18, 2026 * Major * Moved invoice downloads from `/v1/invoices/{id}/download` GET to `/v2/invoices/{id}/download` GET. * Moved export downloads from `/v1/exports/{exportId}/download` GET to `/v2/exports/{exportId}/download` GET. * Added `UpdateInvoice.subscription_id` on `/v1/invoices/{id}` PATCH endpoint ## August 17, 2026 * Added `User.manager_id` on `/v1/users` GET and `/v1/users/{id}` GET endpoints ## August 14, 2026 * Added `local_tax_number` for customers on `/v1/customers` GET, POST and `/v1/customers/{id}` GET, PUT endpoints * Added `Invoice.customer.local_tax_number` on `/v1/invoices` GET, POST and `/v1/invoices/{id}` GET, PATCH endpoints ## August 10, 2026 * Added `Subscription.do_not_charge_subscription` on `/v2/subscriptions` GET endpoint ## August 8, 2026 * Added `Invoice.additional_display_fields` on `/v1/invoices` GET, POST and `/v1/invoices/{id}` GET, PATCH endpoints ## August 7, 2026 * Added `InvoicingEntity.standalone_credit_note_creation_enabled` on `/v1/invoicing-entities` GET, POST and `/v1/invoicing-entities/{id}` GET, PUT endpoints ## August 6, 2026 * Added `WalletTransaction.remaining_amount` and `WalletTransaction.funding_sources` on `/v1/wallets/{id}/transactions` GET endpoint ## August 4, 2026 * Added `volume` and `bulk` options on `Product.price_configurations[].type` for credit products on `/v1/products` GET, POST and `/v1/products/{id}` GET, PUT endpoints ## August 3, 2026 * Added `phase_duration` option on `Subscription.phases[].products[].metering_interval_type` on `/v2/subscriptions/{id}` PUT endpoint ## July 31, 2026 * Added `/v1/price-configurations/{id}` GET endpoint * Added `Product.price_configurations[].integrations` on `/v1/products` GET, POST and `/v1/products/{id}` GET, PUT endpoints ## July 29, 2026 * Added `ES-CE` and `ES-ML` country code options to customer, invoicing entity, organisation, product price configuration, and subscription template fields ## July 28, 2026 * Added `/v1/taxes/rates` POST endpoint * Added `/v1/taxes/rates/{id}` PATCH endpoint * Added `/v1/taxes/rates/{id}` DELETE endpoint ## July 22, 2026 * Added `CustomProperty.required` on `/v1/custom-properties` GET, POST and `/v1/custom-properties/{id}` PUT endpoints ## July 21, 2026 * Added `/v1/features/{code}` DELETE endpoint ## July 20, 2026 * Added `/v1/customers/{id}/arr-history` GET endpoint * Added `/v1/subscriptions/{id}/arr-history` GET endpoint ## July 17, 2026 * Added `Coupon.deleted_at` on `/v1/coupons` and `/v1/coupons/{id}` GET endpoints * Deprecation warning * Deprecating `Coupon.deletedAt` in favor of `Coupon.deleted_at` on `/v1/coupons/{id}` GET endpoint. The `deletedAt` field will be removed in a future version. ## July 15, 2026 * Added `/v1/products/{id}` DELETE endpoint * Added `subscription_template_id` and `invoicing_entity_id` approval condition fields on `/v1/approvals/workflows` GET, POST and `/v1/approvals/workflows/{id}` GET, PUT endpoints ## July 10, 2026 * Added `Customer.domain` on `/v1/customers` GET, POST endpoints * Added `Customer.domain` on `/v1/customers/{id}` GET, PUT endpoints * Added `Customer.domain` on `/v1/customers/batch` POST endpoint * Added `Customer.domain` on `/v2/customers` GET endpoint ## July 9, 2026 * Added `Product.accounting[].integrations` on `/v1/products` GET, POST endpoints * Added `Product.accounting[].integrations` on `/v1/products/{id}` GET, PUT endpoints ## July 8, 2026 * Added `Quote.crm_opportunity_id` on `/v1/quotes/{id}` PATCH endpoint ## July 7, 2026 * Added `/v1/invoices/send-email` POST endpoint * Added `Subscription.phases[].products[].children_usage_aggregation` on `/v2/subscriptions` GET endpoint * Added `Subscription.phases[].products[].children_usage_aggregation` on `/v2/subscriptions/{id}` GET, PUT endpoints ## July 3, 2026 * Added `Product.credits_grant_mode` on `/v1/products` GET, POST endpoints * Added `Product.credits_grant_mode` on `/v1/products/{id}` GET, PUT endpoints ## July 2, 2026 * Added `/v1/bank-accounts/{id}/transactions` GET endpoint ## June 30, 2026 * Added `quote.activated` webhook * Added `credit_balances` option on `CreateExport.name` on `/v1/exports` POST endpoint ## June 23, 2026 * Added `Subscription.phases[].name` on `/v2/subscriptions/{id}` GET endpoint * Added `SubscriptionPhase.name` on `/v2/subscriptions/{id}/phases` GET endpoint * Added `SubscriptionPhase.name` on `/v2/subscriptions/{id}/phases/{phaseId}` GET endpoint ## June 19, 2026 * Added `/v1/quotes/templates` GET endpoint * Added `/v1/quotes/templates/{id}` GET endpoint ## June 18, 2026 * Added `/v1/approvals/workflows` GET endpoint * Added `/v1/approvals/workflows` POST endpoint * Added `/v1/approvals/workflows/{id}` GET endpoint * Added `/v1/approvals/workflows/{id}` PUT endpoint * Added `/v1/approvals/workflows/{id}` DELETE endpoint ## June 17, 2026 * Added `/v1/catalog/versions` GET endpoint * Added `/v1/catalog/versions/draft` GET endpoint * Added `/v1/catalog/versions/draft` POST endpoint * Added `/v1/catalog/versions/draft/publish` POST endpoint * Added `/v1/catalog/versions/draft` DELETE endpoint * Added `/v1/catalog/versions/{id}` GET endpoint * Added `/v1/catalog/versions/{id}/revert` POST endpoint * Added `/v1/catalog/export` GET endpoint * Added optional `name` and `description` payload fields on `/v1/catalog/versions/draft` POST endpoint * Added `CatalogSnapshot.format`, `CatalogSnapshot.sourceClientId`, `CatalogSnapshot.exportedAt`, `CatalogSnapshot.checksum`, `CatalogSnapshot.trackedEntityTypes`, and `CatalogSnapshot.resources` on `/v1/catalog/export` GET endpoint * Added wallet debit deletion support on `/v1/invoices/{id}/transactions/{transactionId}` DELETE endpoint * Added `netsuite` option on `provider_name` for `/v1/customers/providers-bulk-update` POST endpoint * Added `Product.price_configurations[].price_book_id` support on `/v1/products` POST endpoint ## June 16, 2026 * Added `contract_clause_ids` on `/v1/quotes` POST endpoint * Added `contract_clause_ids` on `/v1/quotes/{id}` PATCH endpoint * Added `cancellation_reason` on `subscription.cancellation_scheduled` and `subscription.cancelled` webhook payloads ## June 15, 2026 * Added `/v1/quotes/{id}/duplicate` POST endpoint ## June 13, 2026 * Added `payment_method_status`, `smart_segment.payment_risk`, `paid_invoice_count`, `paid_late_invoice_count`, `late_payment_rate`, and `average_late_payment_delay_days` segment condition fields on `/v1/customers/segments` GET, POST, PATCH endpoints ## June 11, 2026 * Added `Product.integrations` on `/v1/products` GET, POST endpoints * Added `Product.integrations` on `/v1/products/{id}` GET, PUT endpoints * Added `Coupon.integrations` on `/v1/coupons` GET, POST endpoints * Added `Coupon.integrations` on `/v1/coupons/{id}` GET, PUT endpoints * Added `SubscriptionCoupon.integrations` on `/v2/subscriptions` GET endpoint * Added `SubscriptionCoupon.integrations` on `/v2/subscriptions/{id}` GET endpoint ## June 9, 2026 * Added `/v1/quotes/{id}/finalize` POST endpoint * Added `last_renewal` option on `SubscriptionTransition.application_schedule` on `/v2/subscriptions/transitions` POST endpoint * Added `last_renewal` option on `SubscriptionTransition.application_schedule` on `/v2/subscriptions/transitions` GET endpoint * Added `last_renewal` option on `SubscriptionTransition.application_schedule` on `/v2/subscriptions/transitions/{id}` GET endpoint * Added `WalletTransaction.comment` on `/v1/wallets/{id}/transactions` GET endpoint * Added `comment`, `bank_account_id`, and `reference` on `/v1/wallets/{id}/load` POST endpoint for paid wallet loads * Added `type` on `/v1/wallets/{id}/load` POST endpoint to distinguish paid and free wallet loads * Added `Aggregator.operation` `sql_formula` option on `/v1/aggregators` GET endpoint * Added `Aggregator.operation` `sql_formula` option on `/v1/aggregators/{id}` GET endpoint * Added `Aggregator.formula_sql` on `/v1/aggregators` GET endpoint * Added `Aggregator.formula_sql` on `/v1/aggregators/{id}` GET endpoint * Added `Aggregator.unit_name` on `/v1/aggregators` GET, POST, PUT endpoints * Added `Product.aggregator.formula_sql` and `Product.aggregator.unit_name` on `/v1/products` GET endpoint * Added `Product.unit_name` support on `/v1/products` POST endpoint for seat, dynamic, and credit products ## June 3, 2026 * Added `Customer.taxability` on `/v1/customers` GET, POST endpoints * Added `Customer.taxability` on `/v1/customers/{id}` GET, PUT endpoints ## June 2, 2026 * Added `/v1/audit-logs` GET endpoint ## June 1, 2026 * Added `/v1/features` GET endpoint * Added `/v1/features/{code}` GET endpoint * Added `/v1/features` POST endpoint * Added `/v1/features/{code}` PUT endpoint * Added `/v1/features/{code}/archive` PUT endpoint * Added `/v1/features/{code}/unarchive` PUT endpoint * Added `/v1/products/{id}/features` GET endpoint * Added `/v1/products/{id}/features/{code}` PUT endpoint * Added `/v1/products/{id}/features/{code}` DELETE endpoint * Added `/v1/customers/{id}/features` GET endpoint * Added `/v1/customers/{id}/features/{code}` PUT endpoint * Added `/v1/customers/{id}/features/{code}` DELETE endpoint ## May 31, 2026 * Added one-off quote creation with `invoice` payload on `/v1/quotes` POST endpoint * Added one-off quote update with `invoice` payload on `/v1/quotes/{id}` PATCH endpoint * Added `Quote.type` `one_off` option on `/v1/quotes` GET endpoint * Added `Quote.type` `one_off` option on `/v1/quotes/{id}` GET endpoint * Added `Quote.invoice_id` on `/v1/quotes` GET endpoint for one-off quotes * Added `Quote.invoice_id` on `/v1/quotes/{id}` GET endpoint for one-off quotes * Added `Coupon.repeat` `duration` option on `/v1/coupons` GET, POST endpoints * Added `Coupon.repeat` `duration` option on `/v1/coupons/{id}` GET, PUT endpoints * Added `Coupon.duration` on `/v1/coupons` GET, POST endpoints * Added `Coupon.duration` on `/v1/coupons/{id}` GET, PUT endpoints * Added `duration_count` and `duration_period` on `/v1/promotion-codes` POST endpoint ## 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 endpoints * 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` # Webhooks Source: https://docs.hyperline.co/developers/webhooks Receive webhook messages from Hyperline for entity events and user-triggered custom actions, with signing, delivery, and retry guidance. Webhooks are automated messages that Hyperline sends when something happens in your account. Each webhook has a specific payload for the action it notifies. Hyperline sends it to a unique URL: an HTTPS endpoint on your server. Webhooks are a great way to integrate your application with Hyperline. You can fine-tune product flows and build deeper integrations based on your needs, with little development work on your end. ## Add a webhook endpoint To start listening to webhook messages sent by Hyperline, go to your [webhooks settings](https://app.hyperline.co/app/settings/webhooks) in the app and click **Add Endpoint**. Provide the termination URL that you control, and select the event types you want to listen to. To separate the events you listen to, you can add as many URLs as you want. Hyperline now sends webhook calls to your endpoint when the selected events occur. ## Event types You can find a complete list of the event types and the shape of the event payload in the product Webhooks page, on the **Event Catalog** tab. Here is a preview of the events Hyperline can notify you about: * `customer.created`, `customer.updated`, `customer.archived`, `customer.recovered`, `customer.deleted` * `subscription.created`, `subscription.trial_ended`, `subscription.activated`, `subscription.reactivated`, `subscription.contract_started`, `subscription.contract_renewed`, `subscription.paused`, `subscription.phase_activated`, `subscription.updated`, `subscription.cancellation_scheduled`, `subscription.cancelled`, `subscription.voided`, `subscription.errored`, `subscription.charged`, `subscription.commitment_renewed`, `subscription.reinstated`, `subscription.analytics_updated` * `subscription_transition.completed` * `invoice.created`, `invoice.grace_period.started`, `invoice.late`, `invoice.ready`, `invoice.reminder_sent`, `invoice.settled`, `invoice.errored`, `invoice.chargeback`, `invoice.voided`, `invoice.uncollectible`, `invoice.deleted` * `invoice.batch.creation_succeeded`, `invoice.batch.creation_failed` * `credit_note.ready`, `credit_note.settled`, `credit_note.voided` * `checkout.created`, `checkout.completed` * `payment_method.created`, `payment_method.activated`, `payment_method.errored`, `payment_method.deleted`, `payment_method.expiring_soon`, `payment_method.expired` * `wallet.credited`, `wallet.debited`, `wallet.low_projected_balance` * `credit.created`, `credit.updated`, `credit.balance_refreshed`, `credit.low_balance`, `credit.balance_at_zero`, `credit.topup_transaction_created`, `credit.usage_transaction_created`, `credit.expiration_transaction_created` * `quote.created`, `quote.updated`, `quote.approval_requested`, `quote.approved`, `quote.sent`, `quote.viewed`, `quote.signed`, `quote.voided` * `bank_account.created`, `bank_account.deleted`, `bank_account.errored` * `custom_property.created`, `custom_property.updated`, `custom_property.deleted`, `custom_property.value_created`, `custom_property.value_updated` * `product.created`, `product.updated`, `product.archived`, `product.recovered`, `product.deleted` * `plan.created`, `plan.updated`, `plan.deleted` * `coupon.created`, `coupon.updated`, `coupon.deleted` * `pricebook.created`, `pricebook.updated`, `pricebook.deleted` * `approval_workflow.created`, `approval_workflow.updated`, `approval_workflow.deleted` * `approval_request.created`, `approval_request.step_approved`, `approval_request.step_rejected`, `approval_request.approved`, `approval_request.rejected`, `approval_request.cancelled` * `daily_analytics.ready` * `dataloader.failed` * `aggregator.updated`, `aggregator.threshold_crossed` * `event.price_calculated` * `agent.run.completed` * `custom_action` ## Trigger webhooks with custom actions Custom actions let your team trigger webhook-backed workflows directly from customer, invoice, quote, and subscription pages. An action appears at the top of the pages you select and sends a `custom_action` event when a user clicks it. ### Create a custom action 1. Go to [**Settings** → **Developers** → **Custom actions**](https://app.hyperline.co/app/settings/custom-actions). 2. Click **Add action**. 3. Enter a **Name**. This label appears on the action button. 4. Enter a **Type**. This stable slug identifies the action in the webhook payload as `custom_action_type` and can contain lowercase letters, numbers, and underscores. 5. Select an **Icon**. 6. Select one or more **Entities**: customers, invoices, quotes, or subscriptions. 7. Select where the action appears: **Overview pages**, **Form pages**, or both. 8. Click **Save changes**. A custom action configured for form pages appears only after the entity has been created, such as after a draft quote or subscription exists. When one action is available on a page, Hyperline displays it as a button. When several actions are available, Hyperline groups them in a **Custom actions** dropdown. You can rename this dropdown for your entire workspace under **Dropdown** on the custom actions settings page. Enter a descriptive **Type**, such as `sync_quote` or `send_to_erp`, and avoid changing it after connecting your webhook automation. ### Receive custom action events Configure your webhook endpoint to listen for the `custom_action` event type. Hyperline sends the following payload when a user triggers an action: ```json theme={null} { "event_type": "custom_action", "data": { "custom_action_type": "sync_quote", "origin_entity": "quote", "origin_entity_id": "quo_2xY7kP9mQ4rT8v", "triggered_at": "2026-08-12T19:47:43.000Z", "triggered_by": "usr_8hK3mN5pR2sV6w", "triggered_from": "https://app.hyperline.co/app/quoting/quotes/quo_2xY7kP9mQ4rT8v" } } ``` | Field | Description | | - | - | | `custom_action_type` | The **Type** configured for the custom action. Use it to route the event to the correct workflow. | | `origin_entity` | The entity where the action was triggered: `customer`, `invoice`, `quote`, or `subscription`. | | `origin_entity_id` | The ID of that entity. | | `triggered_at` | The ISO 8601 timestamp when the user clicked the action. | | `triggered_by` | The ID of the Hyperline user who clicked the action. | | `triggered_from` | The URL of the page where the action was triggered. | Checkout sessions do not expire automatically, so Hyperline does not emit a `checkout.expired` event. A checkout remains open until it is completed, cancelled, or errored. ## Consuming webhooks Webhook calls are always `POST` HTTPS requests containing a JSON body with this format: ```json theme={null} { "event_type": ".", "data": {} } ``` Your endpoint must quickly return a 2xx (status code 200-299) response prior to any complex logic that could cause a timeout (max 15s). Another important aspect of handling webhooks is to verify the signature and timestamp when processing them. ## Testing events The easiest way to be more confident in your endpoint configuration is to start receiving events as quickly as possible. Use the **Testing** tab to send example events to your endpoint. After sending an example event, you can select the message to view the message payload, all of the message attempts, and whether it succeeded or failed. Additionally, the **Logs** section gives you a complete view of past call attempts with their date, status, and payload. ## Event delivery ### Replaying events To replay one or more events, find the message in the UI, open the options menu next to any of the attempts, and select **Resend**. This is useful if your service had downtime or if your endpoint was misconfigured. ### Retry schedule Hyperline attempts each message based on the following schedule. Each period starts after the preceding attempt fails: * Immediately * 5 seconds * 5 minutes * 30 minutes * 2 hours * 5 hours * 10 hours * 10 hours (in addition to the previous) If you remove or disable an endpoint, Hyperline also stops delivery attempts to that endpoint. ### Event ordering Hyperline doesn't guarantee delivery of events in the order in which they're generated. You can find more details about why guaranteeing order doesn't really work in [this article](https://www.svix.com/blog/guaranteeing-webhook-ordering). Your endpoint shouldn't expect delivery of events in a specific order. Design your system so that it doesn't require ordering. You can also use the API to fetch any missing objects. For example, you can fetch the subscription details using the ID provided in the `subscription.created` event payload. ### Static source IP addresses In case your webhook receiving endpoint is behind a firewall or NAT, you may need to allow traffic from the static IP addresses of Hyperline's webhook servers. In such scenarios, whitelist the following IP addresses: ``` 52.215.16.239 54.216.8.72 63.33.109.123 2a05:d028:17:8000::/56 ``` ## Best practices ### Handle duplicate events Webhook endpoints might occasionally receive the same event more than once. You can guard against duplicated event receipts by making your event processing [idempotent](https://en.wikipedia.org/wiki/Idempotence). One way of doing this is logging the events you've processed, and then not processing already-logged events. ### Prevent stale data Because Hyperline can retry webhooks, another update can occur once your server is finally able to process the event. Therefore, query the latest version of the related entity upon receiving a webhook. ### Verify webhooks Verifying webhooks is an important part of consuming them. Because of the way webhooks work, attackers can impersonate services by simply sending a fake webhook to an endpoint. This is a potential security hole for your application. To prevent this, Hyperline **signs** every webhook and its metadata with a unique key for each endpoint. You can then use this signature to verify the webhook indeed comes from Hyperline, and only process it if it does. Another potential security hole is what's called replay attacks. A replay attack is when an attacker intercepts a valid payload (including the signature), and re-transmits it to your endpoint. This payload passes signature validation, so your endpoint acts on it. To mitigate this attack, Hyperline includes a timestamp (`webhook-timestamp` header) in every request that indicates when the webhook attempt occurred. Reject webhooks with a timestamp that is more than five minutes away (past or future) from the current time. **Verifying signatures** Each webhook call includes three headers with additional information that you use for verification: * `webhook-id`: the unique message identifier for the webhook message. This identifier is unique across all messages but stays the same when Hyperline resends the same webhook (e.g. due to a previous failure). * `webhook-timestamp`: timestamp in seconds since epoch. * `webhook-signature`: the Base64 encoded list of signatures (space delimited). **Constructing the signed content** To build the content to sign, concatenate the id, timestamp, and payload, separated by the full-stop character (`.`). In code, it will look something like: ``` signedContent = "${webhook_id}.${webhook_timestamp}.${body}" ``` Where `body` is the raw body of the request. The signature is sensitive to any change. Even a small change in the body produces a completely different signature, so don't change the body in any way before verifying. **Determining the expected signature** Hyperline uses `HMAC` with `SHA-256` to sign webhooks. To calculate the expected signature, HMAC the `signed_content` from above using the base64 portion of your signing secret as the key. This is the part after the `whsec_` prefix. For example, given the secret `whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw` you will want to use `MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw`. Here is an example of how you can calculate the signature in Node.js: ```js theme={null} const crypto = require("crypto"); const signedContent = `${webhook_id}.${webhook_timestamp}.${body}`; const secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"; // Need to base64 decode the secret const secretBytes = new Buffer(secret.split("_")[1], "base64"); const signature = crypto .createHmac("sha256", secretBytes) .update(signedContent) .digest("base64"); console.log(signature); ``` This generated signature should match one of the ones sent in the `webhook-signature` header. This header contains a list of space-delimited signatures and their corresponding version identifiers. The signature list is most commonly of length one, though there could be any number of signatures. For example: ``` v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo= v2,MzJsNDk4MzI0K2VvdSMjMTEjQEBAQDEyMzMzMzEyMwo= ``` Make sure to remove the version prefix and delimiter (e.g. v1,) before verifying the signature. # Approval workflows Source: https://docs.hyperline.co/docs/account/approvals Configure approval rules, review steps, notifications, and delegations for quotes, invoices, and credit notes. Approval workflows let you require internal review before a quote can be sent to a customer or a draft invoice or credit note can be finalized. You define which actions need approval, the conditions that trigger a review, and who must approve each step. Approval workflows are available on demand. Contact the team via the in-app chat to enable them on your account. For the approval process and options specific to each document, see: Review quotes before sending them to customers, including approval by the quote owner's manager. Review draft invoices and credit notes before finalization. ## Configure approval workflows 1. Go to **Settings** > **Approvals**. 2. Open the **Workflows** tab. 3. Click **Create workflow**. 4. Under **Applicable flows**, select the actions that should trigger the workflow. 5. Configure the workflow rules and approval steps. 6. Save the workflow. Access to workflow settings depends on your role's [settings permissions](/docs/account/users-permissions#settings-permissions). Managing workflows is separate from permission to approve individual requests. ### Applicable flows Select one or more flows for each workflow: | Flow | Action that requires review | | - | - | | **Quote for new subscription** | Finalize a quote for a new subscription | | **Quote for subscription update** | Finalize a quote to change an existing subscription | | **Quote for one-off invoice** | Finalize a quote for a one-off invoice | | **Invoice finalization** | Submit a draft invoice for finalization | | **Credit note finalization** | Submit a draft credit note for finalization | See [Quote approvals](/docs/quotes/approval) and [Invoice and credit note approvals](/docs/invoices/approval) for details on when each flow applies. ### Rules Rules determine when an action requires approval. Combine conditions with **AND** when all conditions must match, or **OR** when any condition can match. | Conditions | Applicable flows | | - | - | | Total amount, discount amount or percentage, products, coupons, billing interval, customer country, payment method, customer invoicing entity, customer tax ID, non-default payment terms, and creator role | All flows | | Subscription template, billing period, free trial, and contract auto-renew | Subscription quote flows | | Subscription [custom properties](/docs/properties/overview) | Subscription quote flows | | Contract clauses, modified contract clauses, terms and conditions, and quote attachment | Quote flows | When you select more than one applicable flow, Hyperline only offers conditions supported by every selected flow. Changing the applicable flows removes any condition that is no longer compatible. Require approval when the total amount exceeds \$50,000 **OR** the discount is greater than 20%. Either condition triggers a review. Use **AND** instead if you only want a review when both conditions match. #### Discounts for specific products Discount amount and percentage conditions can apply to the whole document or to selected products. Configure the scope directly on the discount condition: 1. Add a **Discount amount** or **Discount percent** condition and set its comparison and threshold. 2. Under **Calculate discount for**, select a scope: * **Whole document**: Compare the discount across the whole document. * **Specific products**: Compare the combined discount for the selected products. 3. For **Specific products**, select one or more products in **Products**. When you select multiple products, Hyperline evaluates their combined discount against the threshold, rather than checking each product separately. Discounts on other products do not contribute to this condition. If none of the selected products is present, the condition does not match. A separate **Products** condition only checks whether a product is present. Combining it with a whole-document discount condition does not restrict the discount calculation to that product. Require approval when the **Discount amount** is greater than €500, with **Calculate discount for** set to **Specific products** and **Products** set to Platform subscription. A quote has a €200 discount on Platform subscription and a €1,000 discount on Support. This condition does not require approval: the discount on Platform subscription is below €500, even though the total document discount is €1,200. ### Approval steps A workflow can contain one or more steps. Hyperline processes them in order, and a request must complete every step before it is fully approved. For each step, configure: | Setting | Purpose | | - | - | | **Step name** | Give the step a descriptive name, such as Finance review. | | **Approvers** | Select individual team members or roles. For quote flows, you can also select [**Manager of quote owner**](/docs/quotes/approval#manager-of-quote-owner). | | **All approvers** | Every selected approver must approve before the request moves to the next step. | | **Any approver** | One selected approver can complete the step. | A large deal requires three steps: a sales manager reviews the commercial terms, a finance team member reviews the billing details, and the CFO or CEO gives final approval. Set each step to **Any approver** if one decision from that step's approvers is enough. ### Workflow priority You can create multiple workflows. When an action matches more than one, Hyperline applies only the workflow with the highest priority (lowest number). To adjust priority, drag and drop workflows in **Settings** > **Approvals** > **Workflows**. ## Notifications When an approval request is created, Hyperline automatically notifies the relevant approvers: * **Email notifications**: Approvers receive an email when their approval is needed * **Delegated approver notifications**: If an approver has an active delegation, the new approver also receives the approval request email when **Email notifications** is enabled on the workflow. See [How delegated approvals work](#how-delegated-approvals-work) * **Slack notifications** (optional): You can connect a Slack channel to each approval workflow. When approval is needed at any step, Hyperline sends a notification to the configured channel. The notification includes details about the quote, invoice, or credit note, the requester, the workflow step, and the approvers Configure Slack notifications in the workflow settings by selecting the channel where notifications should be sent. Learn more about [Slack integration](/integrations/slack). Hyperline can also deliver approval request notifications through each team member's personal notification channels. Team members can manage these from **Profile** > **Notifications**, including Slack DMs when Slack is connected. Slack DMs include request details and actions to **Approve**, **Reject**, or **Open in Hyperline**. Learn more about [profile notifications](/docs/account/users-permissions#manage-profile-notifications). If you receive a Slack approval request, you can approve or reject directly from Slack. If another approver has already acted, the Slack message updates to show the current approval state. ## Approval delegations Approval delegations let an approver temporarily give another active team member the ability to approve or reject requests on their behalf. Use them when an approver is out of office or when another team member needs to cover approvals for a defined period. A delegated decision counts as a decision from the original approver, while Hyperline also records which user actually approved or rejected the request. The approval history shows it as "‹new approver› on behalf of ‹original approver›". A finance manager is away for one week and delegates approvals to another finance team member. During that week, the delegated approver receives approval requests, can approve or reject them, and their decisions count as the finance manager's decisions in the workflow. ### Create an approval delegation You can delegate your own approvals from your profile. This does not require any permission: 1. Click **Profile** in the sidebar. 2. In the **Approval delegation** section, click **Create delegation**. 3. Select the **New approver**. You cannot delegate approvals to yourself. 4. Select the **Period**. 5. Add a **Reason**, if needed. 6. Click **Create delegation**. While your delegation is active or scheduled, the section shows it, with a **Revoke** button, instead of **Create delegation**. To create a delegation for another approver, you need the **Manage approvals settings** permission: 1. Go to **Settings** > **Approvals**. 2. Open the **Delegations** tab. 3. Click **Create delegation**. 4. Select the **Original approver** and the **New approver**. 5. Select the **Period**. 6. Add a **Reason**, if needed. 7. Click **Create delegation**. Keep these rules in mind: * A delegation always has a start date and an end date, and the end date must be in the future * Delegations for the same original approver cannot overlap * The original approver and the new approver must be two different active team members ### How delegated approvals work Hyperline checks delegations when someone approves or rejects, not when the request is created. A delegation therefore covers requests that were already pending when it started, as well as new ones. The original approver can still approve or reject their requests during the delegation. When the new approver approves or rejects a request: * The workflow treats the decision as coming from the original approver * Hyperline records who acted on behalf of the approver * The same **All approvers** and **Any approver** step rules still apply Hyperline does not notify the new approver when a delegation is created, so let them know. During the delegation: * Quotes they can approve through the delegation appear in the **Need your approval** tab of their quotes list * New approval requests are also emailed to them when **Email notifications** is enabled on the workflow * Slack notifications only go to the original approver ### Manage delegation periods Delegations are time-bound. A delegation only applies between its start and end dates. To end it early, revoke it: * From your profile: click **Revoke** on your delegation, then **Revoke delegation** * From **Settings** > **Approvals** > **Delegations**: open the delegation's menu, click **Revoke**, then **Revoke delegation**. This requires the **Manage approvals settings** permission. On your profile, a delegation shows as `Active` or `Scheduled`. The **Delegations** tab lists active and scheduled delegations. Keep these rules in mind: * Ended and revoked delegations no longer grant approval rights * A delegation stops working once the original approver's access is revoked. Delegations cover absences, not departures: see [When an approver leaves](#when-an-approver-leaves) * Past delegated decisions remain in the approval history after a delegation ends or is revoked ## When an approver leaves There is no admin override for approvals: only the approvers configured on a step, or their active delegates, can approve or reject it. Plan the handover before you revoke a departing member's access. ### Before revoking access Reassign everything that routes approvals to the departing member: * **Direct reports**: give each member who reports to them a new manager. See [Set a member's manager](/docs/account/users-permissions#set-a-members-manager). * **Open quotes they own**: change the quote owner, as described in [Manager of quote owner](/docs/quotes/approval#manager-of-quote-owner). * **Approval workflows**: replace them in every step that names them. Alternatively, [merge them into a successor](/docs/account/users-permissions#merge-members). Merging transfers their owned quotes, direct reports, places in approval workflows, approval delegations, and pending approvals in one action. ### After access is revoked Once a member's access is revoked: * Their direct reports no longer have a manager. **Manager of quote owner** steps on those members' quotes are skipped when the step has no other approvers, including on quotes already pending approval. * Their delegations stop working. * Quotes they still own that are waiting on a **Manager of quote owner** step stay blocked until you change the quote owner. When a skipped step was the last one requiring a decision, Hyperline approves the quote without review. If a named approver has already left: 1. Replace them in each workflow step that names them. 2. On each quote waiting on them, click **Edit quote**, then **Finalize quote**. Editing a workflow does not move requests already pending: they stay on the workflow version they started with. Finalizing the quote again starts a new request on the updated workflow. ## Next steps * [Submit and review quotes](/docs/quotes/approval). * [Submit and review invoices and credit notes](/docs/invoices/approval). # Email settings Source: https://docs.hyperline.co/docs/account/emails Configure customer emails, verify a custom sending domain, customize senders and reply-to addresses, and preview templates and sent emails. Configure your emails in **Settings > Emailing**. The settings are organized into three tabs: | Tab | What you can configure | | - | - | | **Customer emails** | Which notifications Hyperline sends to customers. | | **Sending** | Your sending domain, sender and reply-to addresses, and additional recipients. | | **Templates** | Previews of customer emails by language and invoicing entity. | In [test mode](../getting-started/sandbox), these settings still send real emails when the related action occurs. Use internal or dedicated test addresses for sandbox customers and recipients. ## Customer automated emails In **Settings > Emailing > Customer emails**, enable or disable each notification, then click **Save changes**. | Email | When it is sent | | - | - | | **Invoice to pay (manual payment)** | When an invoice with a manual payment method, such as bank transfer, is generated. | | **Invoice to pay (automated payment)** | When an invoice with an automated payment method is generated. | | **Invoice paid** | When an invoice or document is fully paid, including after recording an offline payment. | | **Payment failed** | When there is an issue with the payment of an invoice. | | **Credit note finalized** | When a credit note is finalized and not yet refunded. | | **Credit note settled** | When a credit note has been applied. | | **Quote signed** | When the customer signs a quote. | | **Checkout session created** | When a checkout session is created for a new subscription. You can override this setting per checkout. | | **Checkout session completed** | When the customer completes checkout. | These settings apply across your account. [Invoice reminders](../invoices/reminders) have their own configuration. For invoice-specific behavior, including e-invoicing, see [Invoice emails](../invoices/emails). ## Custom sending domain A sending domain lets you send customer emails from your own address, such as `billing@alpeak.com`. You need access to your domain's DNS settings, or help from the person who manages your company's domain. ### Add and verify a domain 1. Go to **Settings > Emailing > Sending**. 2. Under **Sending domain**, click **Add domain**. 3. Enter a domain or subdomain you own, such as `alpeak.com` or `mail.alpeak.com`, without `https://`, a path, or an email address. Confirm with **Add domain**. 4. Expand **DNS records** on the domain card. At your domain provider, add each record using the type, **Name**, and **Value** shown in Hyperline. Use the copy buttons to avoid transcription errors. 5. Open the domain's actions menu and click **Check** to refresh its verification status. 6. Once the status is `Verified`, [configure a sender address](#sender-and-reply-to-addresses) for each invoicing entity that should use the domain. For a new domain, configure sender addresses after verification. You can register one custom sending domain per account; an existing deprecated domain can remain alongside it during migration. | Status | What to do | | - | - | | `Pending verification` | Confirm that all displayed DNS records have been added. DNS changes may not be visible immediately; use **Check** again after they propagate. | | `Verified` | The domain is ready to use for custom sender addresses. | | `Verification failed` | Review the record types, names, and values at your domain provider, correct any differences, then click **Check**. | | `Not configured` | Complete the domain setup before using a custom sender address. | Your email sending domain is configured separately from the [custom domain for hosted portal and checkout pages](../customers/portal#set-a-custom-domain). Use the DNS records displayed under **Sending domain** for email verification. ### Migrate a deprecated domain If your existing domain is marked `Deprecated`, register the same domain again with **Add domain** and add the new DNS records shown in Hyperline. Keep the existing domain configuration until the new registration is verified. Once the new registration is verified, Hyperline automatically moves the associated invoicing-entity senders from the deprecated registration to the new one. Review **Senders and reply-to** before deleting the deprecated entry. If you use a different domain instead, update each entity's sender address after verification. ### Delete or replace a domain Open the domain's actions menu, click **Delete**, and confirm. To replace your custom domain, delete it, add and verify the replacement, then configure the affected senders again. Deleting a domain resets the sender addresses associated with it to Hyperline's default sending address. Review the affected invoicing entities before deleting it. ## Sender and reply-to addresses In **Settings > Emailing > Sending**, use **Senders and reply-to** to control the name and address customers see and where their replies go. By default, emails are sent from **Hyperline** at `no-reply@mail.hyperline.co` in production or `no-reply@sandbox.mail.hyperline.co` in test mode. You can customize the sender name, sender email address, and reply-to address independently for each [invoicing entity](./invoicing-entities). ### Set the default reply-to address 1. In the **Default** row, open the actions menu and click **Edit**. 2. Enter the **Reply-to email address** that should receive customer replies. 3. Click **Save changes**. Entities without their own reply-to address use this default. ### Customize an invoicing entity 1. Click **Customize** and select an invoicing entity. To change an existing override, open the entity's actions menu and click **Edit**. 2. Enter the **Sender name**. 3. To use a custom **Sender email address**, verify your sending domain first, then enter only the part before `@`, such as `billing`. Hyperline displays the domain alongside it. If a **Sending domain** selector appears, select the verified domain you want to use. 4. Enter a **Reply-to email address**, or leave it empty to use the account default. 5. Click **Save changes**. You can customize the sender name or reply-to address while keeping the default sender email address. To restore all default sender and reply-to settings for an entity, select **Reset** from its actions menu and confirm. You verify `alpeak.com` and configure an invoicing entity to send emails as **Alpeak Billing** from `billing@alpeak.com`. You set its reply-to address to `finance@alpeak.com` so customer replies reach your finance team. ## Additional email recipients Under **Settings > Emailing > Sending > BCC recipients**, you can add up to five addresses to receive copies of selected customer emails. BCC recipients are hidden from the customer and other recipients. 1. Click **Add recipient**. 2. Enter the recipient's email address and select the email types they should receive. 3. Save the recipient. Use the recipient's actions menu to edit their address or email types, or remove them. This is useful for keeping your finance team or accountant informed. ## Preview email templates 1. Go to **Settings > Emailing > Templates**. 2. Click the **Preview emails** icon next to a template. 3. Select a **Language** and, if your account has multiple entities, an **Invoicing entity**. 4. Review the subject, sender, and email body in the side panel. Template previews use example data to show how an email looks with the selected entity and language. Opening a preview does not send an email. ## Preview sent emails and delivery history 1. Open **Audit logs > Email activity**. 2. Select an email to open its details. 3. Review its recipient, BCC recipients, current status, and related customer, invoice, subscription, or quote. 4. When a saved preview is available, review the subject, sender, and email body as they were sent. 5. Use **History** to follow recorded events, such as sending, delivery, opening, or failure. Sent-email previews are available only for emails whose content was saved when they were sent. Older emails may show details and history without a preview. An opening event identified as likely automated can come from an email security scanner rather than the recipient. ## Next steps * [Invoice emails](../invoices/emails) * [Invoice reminders](../invoices/reminders) * [Invoicing entities](./invoicing-entities) If you need help verifying a domain or configuring your emails, reach out to the Hyperline team via the in-app chat. # Single sign-on and user provisioning Source: https://docs.hyperline.co/docs/account/enterprise-sso Connect your identity provider, provision members automatically, and choose how their roles are managed. Connect Google Workspace or a SAML identity provider to let your team sign in through single sign-on (SSO). User provisioning keeps their Hyperline memberships up to date as they join, change teams, or leave. You choose separately whether to manage their roles in Hyperline, through identity provider groups, or through roles supplied directly by SCIM. ## Before you start Single sign-on and user provisioning are enterprise features available on demand. Contact Hyperline through the in-app chat to enable them for your account. You need **Manage authentication settings** and pop-ups allowed in your browser to configure SSO and user provisioning. **View authentication settings** allows you to review the configuration without changing it. Configure a separate connection for each Hyperline account. See [Settings permissions](./users-permissions#settings-permissions). ## Connect your identity provider You need a Google Workspace administrator account and the Google Admin SDK Directory API enabled for users and groups. 1. Open **Settings > General**. In **Single sign-on**, click **Set up** and select **Google Workspace**. 2. Complete the setup assistant to configure sign-in and verify your domain, then return to Hyperline. 3. Click **Configure** next to **Directory synchronization from Google Workspace**. Authorize access to both users and groups with your administrator account. 4. Keep the authorization window open until synchronization completes. **Directory synchronization** changes from `In progress` to `Connected`. Hyperline retrieves directory users and groups automatically. You can also [start a manual synchronization](#manage-your-connection). Single sign-on can show `Connected` before directory synchronization is ready. Complete both steps to use automatic provisioning. You need administrator access to an identity provider that supports SAML 2.0 authentication and SCIM 2.0 user and group provisioning. 1. Open **Settings > General**. In **Single sign-on**, click **Set up** and select **SAML and SCIM**. 2. Follow the setup assistant to configure SAML and SCIM in your identity provider. Keep the setup window open until configuration is complete. 3. Return to Hyperline and confirm that **SCIM provisioning** shows `Configured`. Your identity provider sends user and group changes through SCIM; Hyperline does not offer manual synchronization for these connections. Completing SAML setup or reconfiguration with SCIM configured automatically enables **Provision users in Hyperline**, even if you previously turned it off. Ask your identity provider administrator to configure the [user fields and SAML mapping](/developers/scim-provisioning#user-fields-and-saml-mapping). Keep each member's permanent identifier unchanged when their name or email changes, and update the existing user rather than create a replacement. Hyperline initially links users by email, and sign-in still looks up members by email. After linking, provisioning can update the same member using their stable identity, but the new email must reach Hyperline before they sign in. Creating a SCIM user with a different email does not automatically link their old account. Contact Hyperline through the in-app chat before changing users' emails or your organization's domain to coordinate the change and preserve access. ## Configure provisioning and roles Single sign-on controls how members sign in. [**Require single sign-on**](#require-single-sign-on) makes your configured SSO connection mandatory for account access. **Provision users in Hyperline** controls automatic membership updates. **Sync roles from identity provider groups** separately controls whether group memberships determine roles. | Setup stage | What changes in Hyperline | | - | - | | No SSO connection registered yet | Enterprise provisioning does not create memberships or change roles. Your normal invitation and role-management workflows continue while you complete setup. | | SSO connected, user provisioning off | Members with access can use SSO. Identity provider changes do not create, suspend, remove, or change the roles of memberships in this account. You can edit roles manually. | | SSO connected, user provisioning on | Hyperline imports users and manages their memberships. Role assignment follows the rules below. | For SAML and SCIM, completing setup with SCIM configured enables user provisioning automatically. Group role sync is off by default for new connections. Reconfiguring an existing connection keeps its group role sync setting, so review it before completing setup. ### Choose how roles are managed Choose whether to assign roles manually in Hyperline, through identity provider groups, or directly through SCIM. The following table applies while user provisioning is on; account owners are excluded from automatic role changes. If a direct SCIM role is stored, follow the SCIM rows regardless of the group role sync setting. | Role setup | Existing active member | New member | | - | - | - | | Manual: group role sync off, no direct SCIM role stored | Keeps their current role | Receives the default role | | Groups: group role sync on, a valid mapping matches | Receives the mapped role | Receives the mapped role | | Groups: group role sync on, no valid mapping matches | Receives the default role | Receives the default role | | SCIM: a valid role is supplied directly | Receives the SCIM role, regardless of group role sync | Receives the SCIM role | | SCIM: an empty role list (`roles: []`) is supplied | Receives the default role, regardless of group role sync | Receives the default role | | SCIM: the role is unknown, deleted, belongs to another account, or is ambiguous | Update fails; membership stays unchanged | Provisioning fails | Direct SCIM roles take precedence over group mappings and manual assignments. They are available only for SAML and SCIM connections. Omitting the role attribute from a later update does not clear a role previously supplied through SCIM; see [Assign roles directly through SCIM](#configure-your-chosen-role-management-method) before switching methods. Without a direct SCIM role, group role sync uses the first valid matching mapping by priority, then creation time. A member receives one role, even if several groups match. For existing active members, no groups, no mappings, and no matching groups lead to the default role **only when group role sync is on**. While provisioning is on, you can edit roles in **Settings > Team > Members**, subject to your permissions. This only works when group role sync is off and no direct SCIM role is stored. Hyperline rejects manual changes to a role managed through SCIM and asks you to change it in your identity provider. Pausing user provisioning allows manual role edits, even if group role sync remains selected. ### Choose a default role Open **Settings > Team > Roles > Role provisioning**, select the **Default role**, and click **Save changes**. If none is selected when provisioning is enabled, Hyperline uses the account's standard default role. The default is the fallback shown in the table above. While group role sync is off and no direct SCIM role is stored, changing it preserves existing members' roles. Returning members follow the [reactivation rules](#manage-your-connection). ### Enable user provisioning In **Settings > General > Single sign-on**, enable **Provision users in Hyperline** and click **Save changes**. This setting is available once directory synchronization or SCIM provisioning is configured. Hyperline imports existing identity provider users and applies future profile and membership changes. If an email matches an existing Hyperline user, the identity provider manages their membership in this account, except for account owners. Keep group role sync off while preparing mappings. If you re-enable provisioning on a connection where group role sync is already on, review and confirm the proposed roles before saving. ### Configure your chosen role management method Keep **Sync roles from identity provider groups** off and leave the direct SCIM user-role mapping unconfigured in your identity provider. Assign roles in **Settings > Team > Members**. If you previously used another method, follow [Pause provisioning or switch role management](#manage-your-connection) before making manual assignments. Your finance lead assigns roles in Hyperline while Google Workspace creates and removes members automatically. Keep provisioning on and group role sync off. New members receive the default role; directory updates preserve the roles your finance lead assigns. You can inspect groups and save mappings while group role sync is off. Preparing or editing these mappings does not reassign existing members until you activate synchronization. ```mermaid theme={null} flowchart LR A[Receive groups] --> B[Save mappings] B --> C[Preview roles] C --> D[Activate and apply roles] ``` 1. Confirm that your provider has synchronized the required groups and memberships. Google Workspace synchronizes them automatically; for SAML and SCIM, configure your identity provider to push them. 2. Open **Settings > Team > Roles > Role provisioning**. Click **View groups**, then **View members** to check the received memberships. Use the pagination controls to review additional results. 3. Click **Add mapping**, select a group and a Hyperline role, then save. Repeat for each group. You can map each group once and use its actions menu to edit or delete the mapping. 4. Return to **Settings > General > Single sign-on**, enable **Sync roles from identity provider groups**, and click **Save changes**. 5. Review the current and proposed roles, then click **Activate role synchronization**. Cancel to continue preparing mappings without applying them. Activation applies the mappings to existing members as well as new ones. Check default-role assignments in the preview: members without a matching group receive the default unless a direct SCIM role takes precedence. Once activated, changes to group memberships, mappings, or the default role automatically update provisioned members' roles. For SCIM, push group membership changes through provisioning; members do not need to sign in again, and SAML group attributes do not replace these updates. The preview reflects the directory at the time you review it; later membership changes continue to synchronize. For connections with 1,000 or more directory users, contact Hyperline through the in-app chat before activation. The preview is unavailable because it cannot confirm the complete directory. For SAML and SCIM connections, configure your identity provider's SCIM `roles` attribute to send: * A `value` containing the exact name or ID of an existing role in this Hyperline account, such as `Admin`. SCIM does not create roles. * One role entry, or exactly one entry with `primary` set to `true` if your provider sends several. Keep **Provision users in Hyperline** enabled. The [role assignment table](#choose-how-roles-are-managed) shows how valid, empty, and invalid role values are handled. Do not send an empty role list to mean "leave the role unchanged": it explicitly selects the default role. To switch to manual roles or group mappings, contact Hyperline through the in-app chat before removing the user-role mapping from your identity provider. Simply stopping the attribute from being sent does not clear the previously stored role. For an existing connection, contact Hyperline through the in-app chat to confirm that SCIM role attributes are enabled. Configuring the attribute in your identity provider alone may not be sufficient. ## Assign managers through SCIM For SAML and SCIM connections, you can synchronize each provisioned member's manager from your identity provider. Keep **Provision users in Hyperline** enabled; manager updates do not depend on **Sync roles from identity provider groups**. Google Workspace directory synchronization does not synchronize managers. 1. Provision the manager through the same connection first and confirm that they are a member of the same Hyperline account. 2. In your identity provider's attribute mappings, map the manager to the enterprise SCIM `manager.value` field: `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.value`. Send the manager's SCIM user `id` returned during provisioning, not their email address or `externalId`. 3. Push the member's update from your identity provider, then check the **Manager** column in **Settings > Team > Members**. To remove an assignment, configure your provider to send an explicit empty or null manager value. Omitting the attribute does not clear a previously supplied manager. A member cannot be their own manager. If the manager has not been provisioned through the same connection or is missing from the account, Hyperline cannot apply the update. Provision the manager, then push the member's update again. You can still [edit managers manually](./users-permissions#set-a-members-manager), but later provisioning can overwrite your changes with the manager supplied by your provider. Account owners are excluded from automatic manager updates. Pausing user provisioning pauses manager updates too. ## Share the login link After single sign-on shows `Connected`: 1. Open **Settings > General > Single sign-on**. 2. Click **Copy login URL** next to **SSO login URL**. 3. Share the link with your team so they can sign in through your identity provider. Copy the link from the account and environment members need to access: sandbox and production have separate links. Members can bookmark it; entering an email on the standard login page does not automatically select your enterprise connection. ## Require single sign-on By default, connecting your identity provider makes SSO available without requiring it. Enable **Require single sign-on** to require members, including account owners, to use the configured SSO connection when accessing this account. 1. Open **Settings > General > Single sign-on** and confirm that single sign-on shows `Connected`. 2. Copy the **SSO login URL**, test it in a private browser window, and share it with your team before enabling the requirement. 3. Enable **Require single sign-on** and click **Save changes**. The requirement applies to existing sessions too. This includes members signed in through another method, such as a password or the standard **Continue with Google** button. When they next access the account, they return to the login page with a **Single sign-on required** message. They must use the account's **SSO login URL** to sign in through the configured connection. Having a provisioned membership does not make an existing session an SSO session. **Require single sign-on** is independent of **Provision users in Hyperline** and **Sync roles from identity provider groups**. Pausing provisioning does not remove the sign-in requirement, and requiring SSO does not provision members or change their roles. The setting applies to this account only. Configure sandbox and production separately, using each environment's login link. To allow other sign-in methods again, turn off **Require single sign-on** and click **Save changes**. You must also turn it off before deleting the connection. If you cannot sign in through SSO to change the setting, contact Hyperline through the in-app chat. ## Manage your connection * **Turn group role sync off:** existing roles and saved mappings remain in place. Hyperline does not restore the roles members had before synchronization. Direct SCIM roles continue to apply while user provisioning is on; you can edit roles manually for members without one. * **Turn user provisioning off:** identity provider changes stop creating, suspending, removing, or changing roles for memberships in this account, including direct SCIM role and manager updates. Existing memberships, roles, managers, and saved settings remain. You can edit roles manually without changing the saved group role sync setting. * **Re-enable provisioning:** Hyperline imports users and checks previously linked memberships again. Suspensions and deletions made during the pause can now remove access. If group role sync is already on, mapped and default roles apply; direct SCIM roles apply independently of that setting. Review your provider's users and the proposed assignments before saving. For SAML and SCIM, completing setup or reconfiguration with SCIM configured turns user provisioning back on. Check both provisioning and role settings afterward. In **Settings > General > Single sign-on**, click **Reconfigure** to reopen the setup assistant. You can update sign-in, finish domain verification, or complete SCIM configuration without deleting the connection. Hyperline refreshes its details when you close the assistant. For Google Workspace directory authorization, use **Configure** in the directory synchronization line. For SAML, follow the [provider setup instructions](#connect-your-identity-provider) and review provisioning after reconfiguration. Reconfiguration does not migrate existing SAML login identities. If you are switching from UUIDs to email-based sign-in or renaming existing users, coordinate the [identifier migration](/developers/scim-provisioning#existing-connections-and-identifier-changes) with Hyperline before changing your provider's sign-in mapping. In **Settings > General > Single sign-on**, click **Synchronize now** and confirm. Synchronization runs in the background. **Last synchronization** displays its date and time; hover over `Failed` if shown to read the provider error. Google Workspace also synchronizes automatically. A new manual synchronization cannot start if the connection was synchronized during the previous 30 minutes. * While provisioning is on, suspending or blocking a user in your identity provider removes their provisioned access. Restoring them reactivates the existing membership. * A returning member follows the current SCIM or group role rules. With group role sync off and no direct SCIM role stored, they keep their previous role if it is still valid; otherwise, they receive the default. * Removing a member from a mapped group recalculates their role when group role sync is on: another matching mapping applies, or the default if none matches. A direct SCIM role still takes precedence. * Deleting a user removes linked memberships only in accounts where user provisioning is on, except account owner memberships. Accounts with provisioning paused keep their memberships until it is re-enabled. * If a member has several identities in the same connection, suspending or deleting one keeps their membership while another identity in that connection remains active. * Account owners are never automatically suspended or removed. * Memberships that remain manually managed in other accounts are unaffected. You can still invite members manually. In **Settings > Team > Members**, hover over a provisioned member's **SSO** badge to see their identity provider. Remove their access through that provider; role editing follows your [role management settings](#choose-how-roles-are-managed). ## Troubleshooting Only authentication setup is complete. Click **Configure** in the directory synchronization line and authorize access with a Google Workspace administrator account. For Google Workspace, confirm that the Google Admin SDK Directory API is enabled and access to both users and groups was authorized. Click **Synchronize now** in **Settings > General** and wait for completion. For SCIM, confirm that your identity provider has pushed the group and its memberships. Then reopen **View groups** or the group selector. Click **Reconfigure** and complete SCIM configuration in the setup assistant and your identity provider. Confirm that your provider is configured to provision both users and groups. This account requires its configured SSO connection. Open the [SSO login URL](#share-the-login-link) shared by your administrator for the correct account and environment. A password or standard Google login does not satisfy the requirement. If the message persists after using that link, ask your administrator to check your access to the Hyperline application in your identity provider, then contact Hyperline through the in-app chat. Use the [dedicated login link](#share-the-login-link) to start your enterprise sign-in flow. SAML setup also enables sign-in from your identity provider. Try **Reconfigure** to refresh the connection, or use the **SSO login URL** to start from Hyperline. Contact Hyperline through the in-app chat if the issue persists. Confirm that **Directory synchronization** shows `Connected` for Google Workspace or **SCIM provisioning** shows `Configured` for SAML. Check that **Provision users in Hyperline** is enabled and users are included in synchronization or assigned to the Hyperline application in your provider. For SCIM, also review your provider's provisioning logs. Hyperline processes SCIM requests and membership updates separately. Allow the update to finish, then refresh **Settings > Team > Members**. Confirm that provisioning is enabled and the request used this account's connection. An invalid role or a manager who has not been provisioned can prevent the member update from being applied. Correct the supplied value and push the update again. If it still does not apply, contact Hyperline through the in-app chat with the affected member and request time. Updating attribute mappings does not fill missing values on existing users. Ask your identity provider administrator to resend each user's current status and original permanent identifier to the existing SCIM user. Do not recreate users or assign new identifiers to repair missing fields. See [Repair missing fields](/developers/scim-provisioning#repair-missing-fields-on-existing-users). Separate identities for sandbox and production are expected: each account has its own connection, login link, and provisioned users. Do not delete one just because the email also exists in the other environment. If several identities exist inside the same connection, contact Hyperline through the in-app chat before deleting or recreating them. A sign-in identity may be linked to the existing provisioned user; removing it can interrupt SSO. Check the permanent identifier, login name, and email mappings with your identity provider administrator first. Check that **Provision users in Hyperline** and **Sync roles from identity provider groups** are enabled and saved. Use **View groups > View members** to confirm the member belongs to the mapped group. If your provider also supplies a SCIM user role, that role takes precedence. Review your [role management method](#choose-how-roles-are-managed) before changing the configuration. While user provisioning is on, change group-managed or direct SCIM roles in your identity provider. To manage roles manually, pause user provisioning or follow the instructions for switching role management methods. If Hyperline cannot verify whether SCIM manages the role, retry after the provider connection is available. A directory error stops the preview; it does not assign the default role to users whose groups could not be loaded. Resolve the provider error and retry. Reading groups, inspecting members, and previewing roles do not change existing roles. Hover over `Failed` next to **Last synchronization** to read the provider error. Resolve the Google Workspace configuration or authorization issue, then click **Synchronize now**. ## Related * [SCIM provisioning reference](/developers/scim-provisioning) * [Users & permissions](./users-permissions) * [Account settings](./settings) # Invoicing entities Source: https://docs.hyperline.co/docs/account/invoicing-entities Manage multiple billing profiles under one Hyperline account with invoicing entities, each with its own tax setup, legal info, and payment methods. Invoicing entities let you **manage multiple billing profiles under a single Hyperline account**. Each entity shares the account configuration (products, plans, events, coupons, and integrations). However, each entity has its own distinct invoicing settings (business information, invoice legal information and terms, tax setup and default payment methods). This makes it easy to **centralize your global billing configuration** while customizing how each entity invoices its customers, whether you’re operating across countries, business units, or brands. You can connect accounting integrations to a specific invoicing entity (e.g. Pennylane for an entity based in France, QuickBooks for one based in the United States). You can also use the [API Reference](/api-reference/endpoints/invoicing-entities/list-invoicing-entities) to create and manage invoicing entities. ## Create invoicing entity You can create invoicing entities from **Settings** by clicking your company name while browsing an invoicing entity subpage. You can create an unlimited number of invoicing entities. An invoicing entity has its own invoicing settings: * **Business information**: it can have its own trade name, logo and brand color, billing address, accounting currency, default timezone and languages. This is useful for companies operating under different business names in different countries. * **Invoicing**: Activate e-invoicing, add different invoicing patterns and legal information, payment terms, initiation delay, grace period for invoices, credit notes and documents. You can also override the [reverse-charge legal statement](../invoices/tax-management#customize-the-reverse-charge-statement) printed on reverse-charge invoices per invoice language. The **Credit notes** section also includes the [Allow credit notes without an invoice](../invoices/refunds#allow-credit-notes-without-an-invoice) switch, which controls whether you can create standalone credit notes for the entity (allowed by default). This is helpful if your different entities have their own legal constraints or ways to operate business. * **Taxes**: Select the tax engine (Hyperline, Anrok, Sphere, manual), activate automatic tax collection, configure customer tax identifiers, and manage tax mappings. * **Payment methods**: Select available payment methods and the default payment provider or bank account for each of them. For bank transfers, you can keep one bank account or bank transfer provider for all invoices. You can also switch to **Advanced** mode to route invoices to different bank accounts or providers based on invoice currency, customer country, and/or customer segment. ## Email senders In **Settings > Emailing > Sending**, you can customize the sender name, sender email address, and reply-to address independently for each invoicing entity. A custom sender address requires a verified sending domain. Entities without overrides use the default settings. See [Sender and reply-to addresses](./emails#sender-and-reply-to-addresses) for setup instructions. ## Delete invoicing entity You can delete an invoicing entity from **Settings** > **Invoicing entities**. Open the entity's actions menu, click **Delete**, then confirm in the modal. Deleting an entity requires the settings update permission. A few rules apply: * **Existing invoices are preserved**. Deleting the entity does not remove the invoices it issued. * **The default invoicing entity cannot be deleted**. The Delete action is disabled for it; set another invoicing entity as default first. * **The entity must have no active dependencies**. Hyperline blocks the deletion and returns an error if the entity is still linked to customers, running subscriptions, quotes, or customer segments. Reassign or remove these elements before deleting the entity. ## Payment methods You configure payment methods separately for each invoicing entity. This lets you select the payment methods that the entity can offer and set the default payment provider or bank account used for each method. To review these settings, go to **Settings** > **Invoicing entities**, select the invoicing entity, then open **Payment methods**. These settings act as the defaults for the entity's customers. Customers set to **Use default settings** for a payment method inherit the entity configuration, and updating the entity settings automatically applies to those customers. Customers with an explicit override or a disabled method are not affected. See [customer-level configuration](../payments/payment-methods#inherit-override-or-disable-a-method) for details. ### Configure bank accounts for bank transfers For bank transfers, the selected bank account or provider determines the transfer details Hyperline adds to an invoice. In the **Bank transfer** row, you can select a single bank account or bank transfer provider used for every invoice. You can also switch to **Advanced** mode to route invoices to different destinations based on the invoice and customer. Advanced mode requires at least one bank account or a connected bank transfer provider (such as Mollie) for the invoicing entity. #### Advanced mode In Advanced mode, you define a list of **mappings**. Each mapping combines one or more criteria with the destination to use when the criteria match: * **Currency**: match invoices issued in a specific currency. * **Country**: match customers based in a specific country. * **Segment**: match customers that belong to a specific segment. Each mapping targets one of two destination types: * **Bank account**: Hyperline prints the account details on the invoice, and your customer sends the transfer directly to that account. You reconcile incoming payments yourself. * **Bank transfer provider** (such as Mollie): the connected provider handles the transfer and collects and reconciles payments automatically. Each mapping must specify **at least one criterion** and **exactly one destination**, either a bank account or a provider, never both in the same mapping. Criteria within a mapping are combined with AND. For example, a mapping with `Currency: EUR` and `Country: France` only applies to invoices in EUR issued to customers based in France. You can save the settings only once the mappings table has at least one row. When an invoice is generated, Hyperline picks the destination of the mapping whose criteria match the invoice and its customer. For a bank account, Hyperline adds those account details to the invoice; for a provider, the provider's transfer instructions apply. Mappings that combine more criteria are considered more specific than mappings with fewer criteria. To configure mappings, open the **Bank transfer** row, select **Advanced**, then click **Add mapping** for each rule you need. Click **Save changes** when you are done. See [Payment methods](../payments/payment-methods) for details about supported methods, payment service providers, and customer-level configuration. ## Tax enforcement Tax enforcement settings are scoped to each invoicing entity. In **Settings** > **Taxes**, you can: * Enable **Enable local tax number** when company customers billed by this entity need a country-specific tax number in addition to, or instead of, a Tax ID. * Enable **Require customer tax identifier** when company customers must provide a Tax ID before they can complete their billing details. If local tax numbers are enabled, a local tax number also satisfies this requirement. * Enable **Require valid tax ID for reverse charge** when reverse charge should apply only after the customer's tax ID has been externally validated. See [Tax management](../invoices/tax-management#tax-enforcement-options) for details on validation statuses, VIES, and reverse charge behavior. ## Customer-level configuration You assign invoicing entities at the customer level, and each customer is linked to a single invoicing entity. Updating a customer’s invoicing entity does not impact existing active subscriptions; only new subscriptions created after the update will reflect the change. When customers are created via CRM integrations or other automated flows, Hyperline automatically assigns an invoicing entity based on the customer’s country. If Hyperline finds no country-specific match, it uses the default invoicing entity instead. ## Reporting You can filter your dashboard by invoicing entity, allowing you to have a global view on the entity's business metrics. You can also find the invoicing entity in most exports, allowing you to do your own data analysis. You can use the API to fetch elements like customers or invoices that match a specific invoicing entity. # Account settings Source: https://docs.hyperline.co/docs/account/settings Configure general Hyperline account settings including account name, supported currencies, email notifications, saved views, and Markdown formatting. Account settings control how your account is configured and how billing documents and emails behave across Hyperline. ## Permissions Your role controls which settings you can view and manage. Settings permissions are grouped in one **Settings** section in the role editor, with separate **View** and **Manage** permissions for each area. **Manage** includes **View** for that area. See [Settings permissions](./users-permissions#settings-permissions) for the full list. A page can contain fields from several areas, so access to the page does not necessarily allow changes to every field. ## General settings Use **Settings > General** for workspace-level settings such as your account name and security options. You configure billing details at the invoicing entity level instead of the general account level. See [Invoicing entities](./invoicing-entities) to configure each legal entity's billing profile. ## Approvals Use **Settings** > **Approvals** to configure internal reviews for quotes, invoices, and credit notes. See [Approval workflows](./approvals) to set up rules, approval steps, notifications, and delegations. ## Currencies Hyperline supports multiple currencies for products, prices, subscriptions, quotes, and invoices. Changing currency configuration requires **Manage platform settings**. The main currency concepts are: | Currency | Where it applies | | - | - | | Customer currency | The currency used for the customer, quotes, subscriptions, and invoices created for that customer | | Quote currency | The currency selected when the quote is created. It cannot be changed afterward | | Accounting currency | The currency used by an invoicing entity for accounting and converted invoice footer amounts when needed | | Reporting currency | The currency used for aggregated app views such as dashboards and revenue reporting | Payment currency support also depends on the connected payment provider and enabled payment methods. For payment setup, see [Payment methods](../payments/payment-methods). ## Email settings Use **Settings > Emailing** to configure customer emails and sending settings. The page is organized into three tabs: | Tab | What it controls | | - | - | | **Customer emails** | Which customer emails Hyperline sends automatically | | **Sending** | Custom sending domain, sender and reply-to settings per invoicing entity, and BCC recipients | | **Templates** | Email previews by language and invoicing entity | ### Customer emails Use the **Customer emails** tab to enable or disable invoice, credit note, checkout, payment failure, and quote notifications. See [Customer automated emails](./emails#customer-automated-emails) for the full list. For invoice-specific behavior, see [Invoice emails](../invoices/emails). ### Sending Use the **Sending** tab to [add and verify a custom sending domain](./emails#custom-sending-domain), [customize sender and reply-to addresses](./emails#sender-and-reply-to-addresses) per invoicing entity, and [add BCC recipients](./emails#additional-email-recipients). You can manage your domain directly in Hyperline. ### Templates Use the **Templates** tab to preview customer emails by language and invoicing entity, including the subject, sender, and email body. See [Preview email templates](./emails#preview-email-templates) for instructions. ### Preview a sent email Open **Audit logs > Email activity** and select an email to review its recipients, status, saved content when available, and delivery history. Older emails may not have a saved preview. See [Sent emails and delivery history](./emails#preview-sent-emails-and-delivery-history) for details. ## Saved views Saved views let you save filtered list views for customers, subscriptions, and invoices. Use saved views when your team repeatedly works with the same operational slices, such as: * Active enterprise customers * Past-due invoices * Subscriptions renewing soon * Customers owned by a specific team Creating, updating, and deleting saved views requires the **Manage saved views** permission. ## Markdown text Hyperline supports Markdown formatting in selected document text areas, such as invoice legal information and invoice additional information. Common formatting includes: | Syntax | Result | | - | - | | `**text**` | Bold text | | `*text*` or `_text_` | Italic text | | `---` | Horizontal divider | | `- text` | Bulleted list | | `[text](https://www.hyperline.co)` | Link | You can also use variables such as `{{customer_name}}` or custom property slugs when supported by the selected field. ## Related * [Configure your account](../getting-started/configure-account) * [Users & permissions](./users-permissions) * [Invoicing entities](./invoicing-entities) * [Single sign-on and user provisioning](./enterprise-sso) * [Sandbox and test mode](../getting-started/sandbox) * [Payment orchestration](../payments/orchestration) * [Payment methods](../payments/payment-methods) # Users & permissions Source: https://docs.hyperline.co/docs/account/users-permissions Invite or automatically provision team members, configure single sign-on, and assign roles to control access to your Hyperline account. You can invite an unlimited number of team members to access your Hyperline account. Hyperline offers flexible roles and permissions through access control (ACL), allowing you to configure the appropriate access levels for each member of your account. ## Invite members To invite multiple members at the same time, you can specify multiple emails separated with commas in the **Email** field. New members must accept the invite sent to their email address before they can access Hyperline. If the member already belongs to another Hyperline account, they can [switch between accounts](../getting-started/sandbox#multiple-accounts) using the same login credentials. ## Single sign-on and provisioned members You can enable single sign-on and user provisioning with Google Workspace or another identity provider connected through SAML and SCIM. Your provider can then automatically create, update, suspend, restore, and remove memberships for this Hyperline account. Manually invited members remain supported, and identity provider changes do not affect them. Provisioned memberships display a **Provisioned** label. While user provisioning is on, remove or suspend these memberships through the identity provider. You can edit their roles in the member list when **Sync roles from identity provider groups** is off and no direct SCIM role is stored. Hyperline rejects manual changes to roles managed through SCIM; update those roles in your provider instead. Turning **Provision users in Hyperline** off pauses membership and role updates from the provider and allows manual role edits, subject to your permissions. Re-enabling it applies the provider's current membership and role rules again. See [Single sign-on and user provisioning](./enterprise-sso#choose-how-roles-are-managed) to choose between manual roles, SCIM user roles, and identity provider group mappings. ## Set a member's manager You can assign each member a manager: another member of your account. Managers describe your team hierarchy inside Hyperline. Features that need to reach someone's manager can then resolve it automatically, such as the **Manager of quote owner** approver in [quote approval workflows](/docs/quotes/approval#manager-of-quote-owner). To give several members the same manager, select them in the list and select a member in **Set manager**. You can also set an optional **Manager** when inviting a new member, and clear it at any time. A member cannot be their own manager. Changing managers requires the **Manage users settings** permission. For members provisioned through SAML and SCIM, you can also [synchronize managers from your identity provider](./enterprise-sso#assign-managers-through-scim). Manual edits remain available, but later provisioning can overwrite them with the manager supplied by your provider. ## Transfer account ownership The current account owner can transfer account ownership to another member from the team settings. The new owner must already be a member of the account. Only the account owner sees this action. After the transfer, the selected member becomes the account owner and can perform owner-only actions going forward. ## Remove members When a member leaves, revoke their access or merge them into another member. Both actions require the **Manage users settings** permission. If the member approves quotes, manages other members, or owns open quotes, read [When an approver leaves](/docs/account/approvals#when-an-approver-leaves) first. ### Revoke access For a pending invite, the action is **Revoke invite**. To revoke several members at once, select them in the list, click **Revoke access**, type `confirm`, and confirm. Revoked members appear under **Archived** in the members list. You cannot revoke your own access or the account owner's. Members provisioned through your identity provider cannot be revoked in Hyperline: deprovision them in your provider instead. ### Merge members Merging transfers all of a member's data to another member, then removes the merged member. This includes their owned quotes, direct reports, places in approval workflows, approval delegations, and pending approvals. Pending approvals move to the other member without re-finalizing quotes. Past activity, including past approval decisions, is then attributed to the member you merged into. Merging is irreversible. You cannot merge the account owner or a pending invite into another member. A member provisioned through your identity provider can only be the member you merge into, not the one merged. ## Manage profile notifications You can manage your own notification preferences from **Profile > Notifications**. The page is organized into: | Area | What it controls | | - | - | | **Notification channels** | Which personal channels Hyperline can use to notify you | | **Approval notifications** | Which approval events should trigger notifications for you | | **Customer notifications** | Which customer events should trigger notifications for you | | **Followed segments** | Which segments automatically add you as a follower on matching customers | ### Notification channels Use **Notification channels** to decide where Hyperline can deliver enabled personal notifications. * **Slack DM**: sends direct notifications to you in Slack when Slack is connected in your workspace settings You can use **Send test** to check whether Hyperline can send you a Slack DM. If Slack DM is unavailable, Slack may not be connected in your workspace settings, or Hyperline may not find a Slack user for the email address configured in your profile. ### Approval notifications Use **Approval notifications** to select which approval events should notify you. For **Approval requested**, Hyperline notifies you when a quote requires approval from you. ### Customer notifications Use **Customer notifications** to select which customer events should notify you when you are linked to the customer. You can enable or disable: * **Invoice settled** * **Invoice becomes late** * **Payment fails** * **Payment method changes** * **Payment method deleted** * **Monitoring score changes** * **Contract renews soon** Some events only appear when the related feature is enabled. For example, **Monitoring score changes** appears when Customer Intelligence is enabled. To receive a customer notification, you need both: * The event enabled in **Customer notifications** * A recipient link to the customer, either as owner, direct follower, or follower through a segment ### Followed segments Use **Followed segments** to automatically follow every customer that matches a segment. 1. Navigate to **Profile > Notifications**. 2. In **Followed segments**, select a segment. 3. Click **Add**. Following a segment affects who can receive customer notifications. It does not create a separate notification trigger. For example, if you follow a **Late payment behavior** segment and enable **Invoice becomes late**, Hyperline can notify you when a customer in that segment has a late invoice. ## Manage roles You can create custom roles with specific permissions to provide fine-grained access for members based on your needs. By default, Hyperline creates two roles for you: * **Admin**: full access to Hyperline, including the ability to manage products, plans, customers, subscriptions, and settings * **Account Manager**: limited permissions and limited view on Hyperline, allowing them to manage customers, subscriptions, and invoices (ideal for account management teams) You can also create roles for external accountants, finance teams, product and engineering teams, sales representatives, and more. The accounting module has three dedicated permissions: viewing the section, updating its settings, and making recognition adjustments. See [Accounting permissions](/docs/accounting/getting-started#permissions) for what each one unlocks. ### Settings permissions In the role editor, all settings permissions appear under one **Settings** section. Each area has a **View** permission and a **Manage** permission. * **View** lets you open the relevant settings and review their configuration. * **Manage** lets you change that configuration and automatically includes **View** for the same area. * Turning off **View** also turns off **Manage** for that area. | Area | What it covers | | - | - | | **General** | Account name | | **Users** | Team members and roles | | **Billing** | Your Hyperline billing settings | | **Invoicing entities** | Legal entities, taxes, and invoice and quote document settings | | **Payments** | Payment configuration and payment collection settings | | **Platform** | Currencies, emailing, hosted pages, branding, and custom properties | | **Developers** | API keys, webhooks, integrations, and data exporter settings | | **Approvals** | Approval workflows and approval delegations | | **Authentication** | Multi-factor authentication, single sign-on, and user provisioning | For example, **View general settings** lets a member review the account name, while **Manage general settings** lets them change it. Currency configuration belongs to **Platform**, so changing currencies requires **Manage platform settings**. Some pages contain settings from more than one area. Each field follows its own permission: managing an invoicing entity does not automatically allow changes to its branding or payment settings. View access does not grant access to sensitive credentials or billing management actions. Managing approval workflows is also separate from permission to approve individual quotes or other requests. ### Reporting permissions The **Reporting** section lists **View dashboard**, **View reports**, and **View insights** separately. Select the views each role needs. ### Default role One role is the default role. Hyperline automatically assigns this role to members created through a connected integration, such as a CRM. For provisioned members, a connection-specific default role takes precedence over this account default. See [role provisioning](./enterprise-sso#choose-how-roles-are-managed) for how SCIM roles and group mappings affect assignments. Account Manager is the default role for each newly created Hyperline account. You can set the default to another existing role at any time. ### Create new role # 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. Your [accounting rules](./rules) reference accounts to determine which account receives each debit or credit. Two places in the app deal with accounts, and they do different jobs: * **Accounting** > **Settings** > **Chart of accounts** is where you *manage* accounts: add, edit, delete, or sync them from your accounting provider. It lists codes, names, and types only. * The **Ledger** tab is where you *read* them: balances, movements, and the [financial report exports](#export-financial-reports). ## 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** > **Chart of 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. You can't delete accounts with existing journal entry lines. ## Sync accounts from your accounting provider You can pull an existing chart of accounts 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** > **Chart of 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.). ### Use synced accounts in rules After syncing accounts from your provider: 1. Review the imported **Code**, **Name**, and **Type** values. 2. Open **Accounting** > **Settings** > **Rules**. 3. Select the synced accounts in your rule mappings, such as **Revenue account**, **Deferred revenue**, **Accounts receivable**, **Cash / bank account**, or **Payment clearing account**. 4. Add rule filters when the account should only apply to specific products, currencies, countries, billing intervals, coupons, payment methods, or provider accounts. 5. Save the rule and retry or resync any integration issues that were waiting on account mapping. 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. If an account does not appear after syncing, check that the account is active, available for the relevant entity, and visible to the role or user connected to Hyperline. ## Browse account activity Balances and movements live on the **Ledger** tab, the default landing page of the **Accounting** section. The chart of accounts settings page shows no figures. The tab is an expandable list with one row per account. Collapsed, a row shows the account **code**, its **name**, and its **closing balance** for the selected quarter. Expanding a row reveals: * **Opening balance**: the balance carried into the quarter * The **debit** and **credit** movements posted during the quarter * **Closing balance**: opening balance plus the period's movements * A **View journal entry lines** button, which opens the account's [journal entry lines](./entries#journal-entry-lines-drill-down) for that quarter Above the list, you can select the **quarter**, filter by account **Type**, and search by code or name. You can order accounts by **Code** or by **Name**. ## Export financial reports From the **Ledger** tab, the **Export** dropdown produces three reports based on 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. Hyperline notifies you 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 Browse every journal entry from the Journal tab, drill into a single account's lines from the Ledger, and audit accounting activity in any Hyperline ledger. Hyperline posts journal entries automatically from your billing activity. To understand *how* they are produced (the debits and credits behind each billing event), see [how entries are computed](./entry-mechanics). This page covers where you read them. There are two surfaces, and they answer different questions: | Surface | Where | Answers | | - | - | - | | **Journal** tab | **Accounting** > **Journal** | "Show me every entry in this ledger": a flat, paginated table with its own filters and export | | **Journal entry lines** drill-down | **Accounting** > **Ledger** > expand an account > **View journal entry lines** | "Show me what hit *this* account in *this* quarter": a side panel listing the account's lines, with the full entry next to them | The drill-down also opens from an [invoice](/docs/invoices/overview#accounting), via **View in ledger** on any of the invoice's journal entries. ## Journal tab The **Journal** tab lists every journal entry in the ledger, most recent first. | Column | Description | | - | - | | **Entry** | Entry number (e.g. `JE-001`) | | **Date** | Date of the journal entry | | **Rule** | Code of the accounting rule that generated the entry | | **Description** | What the entry was posted for | | **Amount** | Total amount of the entry, in the ledger's functional currency | Click any row to open that entry in a side modal, with the [entry detail](#entry-detail) described below. ### Filters * **Status**: `Posted` or `Draft` * **Account**: only entries touching a given GL account * **Entry date**: a start and end date * **Rule**: the accounting rule that generated the entry * **Search**: search by invoice number, customer, or amount ### Export Click **Export** at the top of the **Journal** tab to download a **general ledger** XLSX. The export respects the filters currently applied (status, account, and entry date range), so you can scope it to a single account, a specific posting state, or any date window. Exports run asynchronously. Hyperline notifies you in-app once the file is ready, and it will be available from **Exports** in the main navigation. ## Journal entry lines drill-down This view answers a per-account question, so it always opens with an account and a quarter in context. Open it from the **Ledger** tab (expand an account, then click **View journal entry lines**) or from an invoice's **View in ledger** action. Journal entry lines drill-down It is a side panel split in two: * **Left**: a paginated list of the journal entry **lines** posted to the selected account during the quarter * **Right**: the full [entry detail](#entry-detail) for the line selected on the left The header shows the context: `[Code] - [Account Name] / Journal entry lines / Q[N] YYYY`. Each row on the left represents a single 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 | Filter the list by **Type** (`Debit` or `Credit`), by **Date range** within the quarter, or search by invoice number, customer, or amount. This view has no export button. To download entries as a spreadsheet, use the [Journal tab export](#export) or the [financial reports](./accounts#export-financial-reports) on the **Ledger** tab. ## Entry detail Both surfaces show the same entry detail: as a side modal from the **Journal** tab, and in the right-hand panel of the drill-down. **Journal entry details** covers the entry itself: * Entry date and status (with the posting date if posted) * Related records (customer, subscription, invoice) when applicable * Original currency, exchange rate, and exchange rate date, shown only when the rate is not 1 **Journal entry lines** lists every debit and credit of the entry: | 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 | A bold **Total** row closes the table. Debits and credits always match. When an entry has lines across multiple products, lines are grouped by account with each product shown as a sub-row. In the drill-down, the line selected on the left is highlighted here. Is something still unclear? Don't hesitate to reach out to our team via the in-app chat if you need additional support. # How entries are computed Source: https://docs.hyperline.co/docs/accounting/entry-mechanics Understand the debits and credits Hyperline posts for each billing event: invoice posting, revenue recognition, usage, settlement, refunds, and credit notes. This page explains the **journal entries** Hyperline posts behind the scenes for each billing event: the actual debits and credits, and why. It complements the [accounting rules](./rules) (which decide *which* accounts are used) and the [journal entries view](./entries) (where you browse the posted result). Your [accounting rules](./rules) decide the exact account each line lands on. The tables below use account **names** (Accounts receivable, Revenue, Output tax…); the **codes** depend on the [chart of accounts](./accounts) attached to your ledger. ## Double-entry basics Every Hyperline journal entry follows standard double-entry bookkeeping: * **Each entry balances.** Total debits always equal total credits. * **Amounts are net of tax on revenue lines.** Tax is always posted separately to the output tax account when the invoice is issued. This applies regardless of how the revenue itself is recognized. * **Entries are immutable once posted.** Corrections are made with reversing entries (for example a [credit note](#credit-notes)), never by editing or deleting a posted entry. * **One functional currency per ledger.** When an invoice is in a different currency, each line stores both the original-currency amount and the converted ledger amount. See [multi-currency](#multi-currency-and-fx). Throughout this page, each event is shown as a small ledger table: | Account | Debit | Credit | | - | - | - | | Example account A | 100 | | | Example account B | | 100 | ## Invoice posted When an invoice is finalized and emitted, Hyperline posts one entry that recognizes the receivable and the tax liability. It books the revenue either **immediately** or as **deferred revenue**, depending on the line item's [revenue recognition](./revenue-recognition) method. ### Immediate revenue For a line with no deferral (no recognition rule, or point-in-time recognized on the invoice date), revenue is booked straight away. A €120 invoice line (€100 net + €20 tax) for a product recognized immediately: | Account | Debit | Credit | | - | - | - | | Accounts receivable | 120 | | | Revenue | | 100 | | Output tax | | 20 | ### Deferred revenue For a line recognized **over time**, by **usage** (billed in advance), or **point-in-time on a future date**, the revenue is parked in deferred revenue at issue. It is released later (see [revenue recognition](#revenue-recognition)). | Account | Debit | Credit | | - | - | - | | Accounts receivable | 120 | | | Deferred revenue | | 100 | | Output tax | | 20 | ### Discounts How a discount appears depends on the **discount recognition mode**, set on the **Revenue recognition** rule: | Mode | Effect on the entry | | - | - | | Immediate | A contra-revenue (or discount) account is debited for the discount amount at issue | | Deferred | A deferred discount account is debited and released on the same schedule as the revenue | | Use net amount | No separate discount line. Revenue is booked net of the discount | ## Revenue recognition Deferred revenue is released to revenue over the service period by a recognition schedule. Each recognition entry (called a **slice**) moves the earned portion out of the liability: | Account | Debit | Credit | | - | - | - | | Deferred revenue | 100 | | | Revenue | | 100 | The recognition method (over-time granularity, point-in-time basis, or usage) drives the timing of these slices. See [revenue recognition](./revenue-recognition) for how each method spreads the amount. Tax is **not** touched at recognition time. It was already posted in full to output tax when the invoice was issued. ## Usage-based revenue Metered products and credit packs are recognized in line with actual consumption. There are two timings, depending on whether the usage is billed **in advance** or **in arrears**, and they post differently. ### Billed in advance The customer is invoiced up front (or buys a credit pack), so the amount sits in **deferred revenue** at issue. Each day, Hyperline releases the share matching that day's consumption: | Account | Debit | Credit | | - | - | - | | Deferred revenue | *(daily usage share)* | | | Revenue | | *(daily usage share)* | Any amount left deferred when a credit pack expires is recognized as **breakage** in a single entry on the expiry date. See [usage-based recognition](./revenue-recognition#usage-based) for the consumption and breakage rules. ### Billed in arrears When usage is billed **after** the period (the invoice is issued at period end for what was already consumed), the revenue is **earned before it is invoiced**. Recognizing it only at invoicing would understate revenue during the period, so Hyperline accrues it daily against a **contract asset** (*unbilled revenue*) instead of deferred revenue. **During the period**, each day's consumption is accrued: | Account | Debit | Credit | | - | - | - | | Unbilled revenue *(contract asset)* | *(daily usage share)* | | | Revenue | | *(daily usage share)* | **When the invoice is issued**, the already-earned amount is reclassified from the contract asset to the receivable. It is not re-recognized as revenue: | Account | Debit | Credit | | - | - | - | | Accounts receivable | *(net + tax)* | | | Unbilled revenue | | *(net already accrued)* | | Output tax | | *(tax)* | If the final invoiced amount differs from what was accrued (late usage, corrections), the difference is **trued up** against revenue at issue. This way, the contract asset nets to zero and recognized revenue equals the invoiced net. Accrual runs **per product** and **per ledger**. A customer consumes a metered product through May and is invoiced €300 + €60 tax on 31 May. Across May, Hyperline accrues the €300 day by day (debit Unbilled revenue / credit Revenue). On 31 May the invoice reclassifies it: | Account | Debit | Credit | | - | - | - | | Accounts receivable | 360 | | | Unbilled revenue | | 300 | | Output tax | | 60 | Revenue was recognized across May as it was earned, not in a lump on 31 May. See [revenue recognition → usage billed in arrears](./revenue-recognition#usage-billed-in-arrears) for the daily timing, the late-usage grace window, and per-product behavior. ## Invoice settled When a payment transaction settles, Hyperline clears the receivable against cash. The debit side depends on the payment method: * **Bank transfer / direct cash** → a **cash** account is debited. * **Payment provider (card, etc.)** → a **payment clearing** account is debited (the funds are in transit until the provider pays out). | Account | Debit | Credit | | - | - | - | | Cash *(or payment clearing)* | 120 | | | Accounts receivable | | 120 | ### Provider fees When the provider deducts a processing fee, the cash received is net of the fee and the fee is booked as an expense: | Account | Debit | Credit | | - | - | - | | Cash *(or payment clearing)* | 117 | | | Payment processing fees | 3 | | | Accounts receivable | | 120 | ### Paying with customer credits When an invoice is settled using a customer's credit balance rather than cash, the credit liability is drawn down instead of debiting cash: | Account | Debit | Credit | | - | - | - | | Customer credits | 120 | | | Accounts receivable | | 120 | ## Refunds A refund reverses a settlement: cash goes back to the customer and the receivable (or a credit) is restored. The legs mirror the settlement entry, debit and credit swapped. | Account | Debit | Credit | | - | - | - | | Accounts receivable | 120 | | | Cash *(or payment clearing)* | | 120 | ## Credit notes A credit note reverses an invoice, posting to the **same accounts** that were used when the invoice was issued. The revenue (or remaining deferred revenue) and the output tax are reversed; the offsetting side depends on whether the invoice was paid: * **Unpaid invoice** → the receivable is reduced (the customer simply owes less). * **Paid invoice** → a **customer credit** liability is created (the value is owed back to the customer). * **Partially paid** → the receivable is cleared first, any excess goes to customer credits. A €120 credit note (€100 net + €20 tax) against an **unpaid** invoice whose revenue was recognized immediately: | Account | Debit | Credit | | - | - | - | | Revenue | 100 | | | Output tax | 20 | | | Accounts receivable | | 120 | Had the invoice been **paid**, the €120 credit would land on **Customer credits** instead of Accounts receivable. If the original line still had **deferred** revenue (not yet fully recognized), the credit note reverses the remaining balance from the deferred revenue account rather than from revenue. This way, it only claws back what was actually recognized. ## Multi-currency and FX Each ledger keeps its books in a single **functional currency**. When an invoice or payment is in another currency, every journal entry line stores: * the **original-currency** amount (as billed), and * the **ledger-currency** amount (converted), plus the exchange rate and rate date used. The rate is captured **at the time of the event** (invoice emission date, payment date) and frozen on the entry, so historical entries are never re-translated when rates later move. The same rate is used across an event's related entries. For example, accrued usage is accrued, reclassified, and trued up at one consistent per-ledger rate so the contract asset nets cleanly. ## Bad debt Configure the uncollectible debit account in your [accounting rules](./rules). Select an asset account to reclassify the outstanding amount as a doubtful receivable, or an expense account for a direct write-off. Hyperline's default rules use **Bad Debt Expense**. When you mark an invoice `uncollectible`, Hyperline posts a journal entry dated on that status change. It clears only the outstanding Accounts receivable balance, so previous partial payments remain settled. For invoices with revenue recognition, Hyperline recognizes revenue scheduled through the write-off date, reverses the remaining deferred revenue, and cancels later recognition entries. | Account | Debit | Credit | | - | - | - | | Deferred revenue | Remaining unrecognized revenue | | | Uncollectible debit account | Balancing amount when the outstanding receivable exceeds deferred revenue | Balancing amount when deferred revenue exceeds the outstanding receivable | | Accounts receivable | | Outstanding invoice balance | The balancing amount is normally a debit. In uncommon partial-payment cases where the deferred revenue reversal exceeds the outstanding receivable, Hyperline credits the configured account instead. This journal entry writes off the receivable. It does not refund or reverse a settled payment through the payment provider. Is something still unclear? Don't hesitate to reach out to our team via the in-app chat if you need additional support. # Getting started with accounting Source: https://docs.hyperline.co/docs/accounting/getting-started Set up accounting in Hyperline: create your first ledger and let Hyperline generate journal entries from your billing activity automatically. Hyperline's accounting module turns your billing activity into journal entries automatically. Every invoice, payment, and credit note posts to your books following rules you control, so your books always match what you billed and deferred revenue is recognized on schedule. No spreadsheets, no manual bookkeeping. The accounting module is not enabled by default. [Contact our team](mailto:support@hyperline.co) or reach out via the in-app chat to have it enabled on your workspace. The module is built around five building blocks: | Building block | What it does | | - | - | | **[Ledger](./ledgers)** | One set of books attached to an invoicing entity. You can keep several ledgers per entity, for example a statutory ledger (the official books you file with tax authorities and auditors) next to a management ledger for internal reporting. | | **[Chart of accounts](./accounts)** | The list of general ledger accounts used in journal entries: accounts receivable, revenue, deferred revenue, tax payable, and so on. Each ledger has its own. | | **[Accounting rules](./rules)** | Define which accounts to debit and credit for each billing event, with filters to scope them to specific products, customers, currencies, or payment methods. | | **[Journal entries](./entries)** | Generated automatically when billing events occur, based on your rules. Posted entries cannot be edited: corrections are made via reversal entries. | | **[Revenue recognition](./revenue-recognition)** | When revenue has to be spread over time, tied to a future date, or matched to usage, Hyperline defers it and recognizes it on schedule automatically. | ## Before you start Make sure you have: * The accounting module enabled on your workspace (see above) * Billing activity to account for (invoices, payments, credit notes), current or upcoming * The accounting standard your books follow (IFRS, US GAAP, UK GAAP, French GAAP, or another local GAAP) * A decision on whether you will sync entries to an external accounting tool, such as Xero, QuickBooks, Pennylane, NetSuite, Exact Online, or Rillet ## Permissions Three permissions, granted to a role in **Settings** > **Team**, control access to the accounting module. See [Users & permissions](/docs/account/users-permissions#manage-roles) for how to create a role. | Permission in the role form | What it unlocks | | - | - | | **View accounting page** | The whole **Accounting** section: ledger, revenue recognition, journal, and settings | | **Update accounting settings** | Creating and editing ledgers, accounts, and rules | | **Make accounting adjustments** | The **Adjust remaining recognition** action on a recognition schedule | **View accounting page** also gates accounting exports: without it, general ledger, income statement, balance sheet, and revenue recognition files are neither visible nor downloadable from **Exports**. ## Setup flow ### 1. Create your ledger A ledger is one self-contained set of books, with its own chart of accounts, rules, and journal entries. Most companies start with a single ledger mirroring the official books they report on. Go to **Accounting** and click **Create ledger**. Configure the following fields, in this order: * **Name**: a label to identify the ledger (e.g. "Statutory IFRS") * **Ledger type**: the accounting standard, which determines the starting chart of accounts and rules * **Invoicing entity**: the entity this ledger is attached to * **Currency**: the **functional currency**, the single currency this ledger keeps its books in. Invoices 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}`). The pattern accepts `{number}` (required, the sequential counter), `{YYYY}`, `{MM}`, and `{DD}` Start with **one statutory ledger** (the official books you file with tax authorities and auditors) and select the type matching your jurisdiction: | Your books follow | Pick | | - | - | | French GAAP (Plan Comptable Général) | `FR GAAP` | | US GAAP (ASC 606) | `US GAAP` | | UK GAAP (FRS 102) | `UK GAAP` | | IFRS or another standard | `IFRS` or `Local GAAP` | If you plan to sync this ledger with an external accounting provider, select the standard that matches your provider's chart of accounts. It simplifies the account mapping later. Leave the `Management`, `Consolidation`, and `Audit adjustment` types for later. They serve advanced setups such as tracking annual and monthly recurring revenue or group-level eliminations. The consolidation and audit types ship without default rules. See [Ledgers](./ledgers#ledger-types) for the full list. ### 2. Accounts and rules are created for you Setting up a chart of accounts and mapping every billing event to the right accounts is usually the tedious part. Hyperline does it for you, based on the ledger type you selected: * A **chart of accounts** matching the selected standard, such as ASC 606 revenue accounts for US GAAP * A complete set of **accounting rules** mapping each billing event (invoice posted, invoice settled, credit note created) to the right accounts Entries post correctly without any extra configuration. You can review everything in **Accounting** > **Settings**, and customize [accounts](./accounts) and [rules](./rules) at any time, for example to map a specific product to its own revenue account. Syncing to an external accounting tool? Instead of using the default accounts, you can [pull the chart of accounts directly from your provider](./accounts#sync-accounts-from-your-accounting-provider) so account codes match exactly. ### 3. Watch entries post From here on, you never write these entries by hand. Each time an invoice is finalized, a payment settles, a credit note is issued, or usage is consumed on a usage-based product, Hyperline applies your rules and posts the matching debits and credits. You can browse them in three places: * **Accounting** > **Journal**: every entry in the ledger as a flat list, with filters for status, account, entry date, and rule * **Accounting** > **Ledger**: entries seen per account, for a selected quarter * The **Accounting** section on any invoice: the entries and recognition schedules for that specific invoice **Entries are not retroactive.** A new ledger only posts journal entries and recognition schedules for events that happen **after it is created** (new invoices, settlements, credit notes, usage). Nothing is generated for your existing billing history. The same applies to changes you make later: editing a rule or an account changes how **future** entries post; it does not recompute entries that are already posted. To bring past periods into the ledger, or to re-apply a corrected rule to a period already posted, [contact our team](mailto:support@hyperline.co) or reach out via the in-app chat. A replay rebuilds the automated entries for the range you ask for, and leaves any [manual recognition adjustments](./revenue-recognition#adjust-remaining-recognition) untouched. ### 4. Verify a first invoice Once a first invoice has been issued, open the invoice page and scroll down to its **Accounting** section. Accounts receivable should equal the total owed, revenue (or deferred revenue) the net amount, and the tax line the tax. If those match, every future invoice will post the same way. To understand exactly which debits and credits Hyperline posts for each event, see [how entries are computed](./entry-mechanics). ## Next steps Scope rules to specific products, customers, or currencies, and understand priorities. Recognition is driven by your accounting rules. Adjust how revenue is deferred and recognized: over time, at a point in time, or based on usage. See the exact debits and credits posted for each billing event. Push invoices to Xero, QuickBooks, Pennylane, NetSuite, and more. Once connected, you can also pull the provider's chart of accounts into your ledger. You can also export financial reports as spreadsheet (XLSX) files. The **Ledger** tab exports the general ledger, income statement, and balance sheet ([details](./accounts#export-financial-reports)); the **Revenue recognition** tab exports the waterfall and the recognized summary ([details](./revenue-recognition#export)). 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/account/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, such as statutory reporting, management accounts, consolidation adjustments, and so on. ## Create a ledger To create a ledger, go to **Accounting** and click **Create ledger**. Configure the following fields, in this order: * **Name**: a label to identify the ledger (e.g. "Statutory – IFRS", "Management") * **Ledger type**: the starting chart of accounts and configuration to apply (see ledger types below) * **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}`). The pattern accepts `{number}` (required, the sequential counter), `{YYYY}`, `{MM}`, and `{DD}` 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. A new ledger starts empty: it posts nothing for billing activity that happened before it was created. See [Getting started](./getting-started#3-watch-entries-post) for how to have past periods replayed into it. ## 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 **Accounting** > **Settings** opens with a read-only **Configuration** block summarizing the current ledger. Click **Edit ledger** there to update its name, type, entity, currency, or journal entry pattern. ## Delete a ledger **Delete ledger** sits alongside **Edit ledger** in the same Configuration block. Deleting a ledger permanently removes its accounts, rules, and journal entries. You can't delete the primary ledger. Deleting a ledger is irreversible. Make sure you no longer need the ledger's history before proceeding. # Manual journal entries Source: https://docs.hyperline.co/docs/accounting/manual-entries Post free-form balanced journal entries in Hyperline for opening balances, adjustments, and corrections that aren't driven by an invoice. Most journal entries in Hyperline are generated automatically from billing events: invoices, payments, credit notes, and revenue recognition. A **manual journal entry** lets you post your own balanced entry directly to a ledger, for activity that has no invoice behind it. Use a manual entry to record: * **Opening balances** when you start using a ledger * **Adjustments** such as accruals, reclassifications, or period-end corrections * **Corrections** to accounting activity that wasn't produced by an invoice Posting a manual entry requires the `accounting_adjust` permission. Entries are **posted immediately**. There is no draft or reversal step. To undo a manual entry, post the opposite entry. ## Post a manual entry 1. Open the **Journal entries** view for the ledger you want to post to. 2. Click **Post journal entry**. 3. Set the **Entry date** and a **Description** (up to 500 characters). 4. Add at least two lines. On each line, select an **Account** and enter an amount in either **Debit** or **Credit**. A single line carries one side only. Click the switch icon on a line to flip its amount between debit and credit. 5. Check the totals. Total debit must equal total credit; the totals turn red while the entry is unbalanced. 6. Click **Post entry**. Posting a balanced two-line manual journal entry ## Accounts managed by Hyperline Some accounts don't appear in the account picker on the entry form. As the form notes, *accounts managed automatically by Hyperline from invoices and payments are hidden from manual entries*. This applies to your **accounts receivable**. A/R driven by invoices is a control account: its balance always equals your outstanding customer invoices, net of payments and credit notes, and Hyperline keeps it reconciled to those invoices. A manual entry has no invoice behind it, so posting one to a managed A/R account would break that reconciliation. To protect it, any account used in an accounts-receivable role by an accounting rule is hidden from the entry form. To record a receivable by hand, create your own separate receivables account in the [chart of accounts](./accounts) and post there. Both accounts still add up to your total accounts receivable on the balance sheet, and the entry stays balanced, so your balance sheet and P\&L remain correct. Keep in mind this manual account is yours to reconcile and clear, and it won't appear in the invoice-based aging. To correct invoice-driven activity, use the matching document rather than a manual entry: issue a [credit note](../invoices/refunds) for a wrong invoice, or fix the payment for misapplied cash. The document posts the correcting entry for you and keeps A/R reconciled to your invoices. ## Revenue recognition on a manual entry When one of your lines **credits a deferred-revenue account** (tagged **Deferred revenue** in the account picker), a **Revenue recognition** section appears on the form. Setting up a recognition schedule is **required**. Deferred revenue is a liability that must be released over time, so Hyperline won't let you post the credit without telling it how. You can defer revenue on **one credit line per entry**. To spread revenue across several deferred accounts, post them as separate entries. In the recognition section you set: * **Recognition method**: **Point in time** (recognize the full amount on a single **Recognition date**) or **Over time** (spread it evenly between a **Start date** and **End date**, at the **Schedule** you select: daily, monthly, quarterly, or yearly). * **Revenue account**: the account the revenue moves to as it is earned. A live preview lists the recognition slices (each period and amount) before you post. For the full mechanics of each method, see [revenue recognition](./revenue-recognition). Post the deferred credit to a **dedicated deferred-revenue account** you control, and check you aren't recognizing the same revenue twice: once here and once from an invoice. Revenue recognition section on a manual entry crediting deferred revenue ## After posting A manual entry sits in the ledger alongside automatically generated entries, with a few markers that set it apart: * It carries a **Manual** tag in the journal entries list. * The **Source** filter lets you show only `Manual` or `Auto-generated` entries. * The entry's detail panel shows its **origin** (manual) and the user who **created** it. Manual entries are included in the [general ledger export](./entries#export) and, when they carry a recognition schedule, appear in the [revenue waterfall](./revenue-recognition#revenue-waterfall) with a manual origin. Is something still unclear? Don't hesitate to reach out to our team via the in-app chat if you need additional 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 recognized 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. Revenue recognition is available on supported plans and may require activation on your account while the feature is being rolled out. If you do not see **Accounting** > **Revenue recognition**, contact support to confirm availability and access. 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. You can set it at the rule level and override it 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 | Recognized each day over the service period | | Monthly | Recognized at the end of each calendar month | | Quarterly | Recognized at the end of each quarter | | Yearly | Recognized 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 recognizes €1,000 each month from January to December. ### Point in time All revenue is recognized 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 recognized. ### Usage-based Revenue is recognized in line with what your customers actually consume. Use this method for **metered products** and **credit packs**. The amount you recognize 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 recognize nothing; busy days recognize more. This covers usage billed **in advance**: the customer prepays (or buys a credit pack) and the amount is deferred at issue. When usage is billed **in arrears** (invoiced at the end of the period for what was already consumed), revenue is accrued against a contract asset instead. See [usage billed in arrears](#usage-billed-in-arrears). #### Recognition timing A daily job sweeps every day's slice. It only releases revenue once the day's usage total has been seen unchanged on two consecutive runs (that is, 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 recognized at the next-but-one daily run (typically two days after the consumption day). A day with **zero** observed usage gets an extra **7 days** before being closed at zero. This way, a slow-starting customer or a delayed ingestion pipeline doesn't permanently zero out an early slice. Two carve-outs to that gate: * **Catching up on old periods.** A day whose period closed more than 7 days ago is recognized on the first pass, without waiting for a second observation. The late-event window has already elapsed. * **Credit-pack drawdown has no grace period.** Drawdown is recognized as soon as it is read. If a drawdown lands late, Hyperline trues the schedule up with an additional slice rather than dropping the amount. Once a day's revenue has been recognized, **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 recognizes each day in proportion to that day's consumption: a day with 50 units recognizes €30, a day with no usage recognizes 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 recognizes 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 recognizes €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 unrecognized remainder is recognized in a single entry on the expiry date as **breakage** (per ASC 606-10-55-46 through 55-49). 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. ### Usage billed in arrears Some metered products are billed **in arrears**: the invoice is issued at the end of the period for usage that already happened. The revenue is therefore **earned before it is invoiced**. Deferring it (as for prepaid usage) would understate revenue during the period. Instead, Hyperline recognizes it as it is consumed and holds it as a contract asset (**unbilled revenue**) until the invoice is issued. Each day during the period, Hyperline recognizes that day's consumption against unbilled revenue (rather than releasing it from deferred revenue). When the invoice is issued at period end, the accrued amount is reclassified from unbilled revenue to accounts receivable. It is **not** recognized again. If the final invoiced amount differs from what was accrued (late usage, corrections), the difference is trued up at issue. This way, unbilled revenue nets to zero and recognized revenue equals the invoiced net. Accrual runs **per product** and **per ledger**, and uses the same daily stability gate as prepaid usage. A day's revenue is released once its usage total has been seen unchanged on two consecutive runs, giving a ≥24 hour grace period for late events. | Setting required | Where to set it | | - | - | | A revenue account | Revenue recognition rule | | An unbilled (accrued) revenue account | Revenue recognition rule | | Metered product billed in arrears | Catalog | A customer consumes a metered product through May and is invoiced €300 (net) on 31 May for that usage. Across May, Hyperline recognizes the €300 day by day as it is consumed, holding it in unbilled revenue. On 31 May the invoice moves the €300 from unbilled revenue to accounts receivable, so no revenue is recognized a second time. See [how entries are computed → usage billed in arrears](./entry-mechanics#billed-in-arrears) for the exact debits and credits at accrual, invoicing, and settlement. ## 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 on the **Revenue recognition** rule: | Mode | Behavior | | - | - | | Immediate | Discount is recognized 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 recognized 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 | ## Revenue waterfall Go to **Accounting** > **Revenue recognition**. The tab shows a single matrix called the **revenue waterfall**. For each **booking month** (the month invoices were issued), it shows how the booked revenue unwinds into recognized revenue across the following months, and how much is still deferred. Read it left to right, under three band labels: | Band | What it holds | | - | - | | **Booked revenue** | One row per booking month; the amount invoiced (net of tax) in that month | | **Recognized revenue** | One column per recognition month. A **past** month shows one `Recognized` column, a **future** month one `Remaining` column, and the **current** month both | | **Total revenue** | The row's **Recognized** total (everything posted so far) and **Remaining** (Booked − Recognized, the deferred balance still on the balance sheet) | Filter the matrix by **year**, **All customers**, **All products**, or search by invoice number, customer name or ID, or subscription ID. All waterfall amounts are net of tax and expressed in the ledger's functional currency. ### Drill into a cell To see what makes up a figure, **double-click** any non-zero cell, or select it and click **Explore** in the floating bar that appears. The drill-down lists the line items behind that cell: | Column | Description | | - | - | | **Product** | The invoiced product | | **Status** | The recognition schedule's status | | **Period** | The service period covered | | **Amount** | The amount contributed to the selected cell | Select a line item to open its full recognition schedule in a sidebar. ### Recognition schedules The sidebar is where a single line item's schedule lives. It shows: * The **customer**, **subscription**, **invoice**, and **product** the schedule belongs to * An **Overview** with the recognized amount against the booked amount, and a progress bar * The amounts **excluding** and **including** tax * The **recognition method** in plain words (e.g. `Over time - Monthly`) * The **service period** * The **Slices** table: one row per recognition slice, with its `Period` and `Amount`, each tagged `Recognized`, `Pending`, `Reversed`, or `Cancelled` ## Adjust remaining recognition Sometimes the schedule Hyperline computed no longer reflects reality: the obligation was satisfied earlier than planned, delivery was renegotiated, or the service period was set up wrong. Click **Adjust remaining recognition** on a schedule to reshape what is left, without touching what has already been recognized. This action requires the **Make accounting adjustments** permission. See [Permissions](./getting-started#permissions). ### The two moves An adjustment combines two moves in a single operation. You can use either or both: * **Recognize now**: release part or all of the remaining deferred balance immediately. Hyperline posts one entry in the current open period, debiting deferred revenue and crediting revenue. * **Spread the remaining**: re-plan whatever is still deferred over a new **From** → **To** window. If anything has already been recognized on the schedule, **From** is locked to the day after the last recognized slice. Adjustments only ever look forward. Three things never change, whatever you do: * The **booked total** stays the same. An adjustment moves revenue in time but never creates or destroys any. * **Already-recognized amounts are never touched.** * A **quarterly or yearly** schedule keeps its periodicity when re-spread. It is not silently converted to monthly. ### Preview before applying The editor previews the result before you commit. Each resulting slice is listed with its new amount, and where an amount changed, the old one is struck through next to it. Slices covering the already-recognized span are tagged **Settled**, and any amount you chose to recognize immediately is tagged **Now**. ### Reason A **Reason** is mandatory because it makes the adjustment auditable: | Reason | Use it when | | - | - | | `Obligation satisfied early` | Delivery completed ahead of the planned schedule | | `Renegotiated delivery or ramp` | The commercial terms changed | | `Service-period change` | The period itself moved | | `Correcting a setup error` | The original schedule was wrong | | `Other` | Anything else. A free-text description is then required | ### Audit trail Hyperline records every adjustment on the schedule under **Manual adjustments**: who made it, when, how much was recognized early, the new recognition window, the reason, and a link to the journal entry that was posted. Each slice the adjustment produced also carries a **Manual** badge in the **Slices** table, so an automated slice is never mistaken for a hand-made one. The [recognized summary export](#export) carries the same `auto` / `manual` distinction. ### When a schedule can be adjusted The **Adjust remaining recognition** button is available when all of the following hold: * The schedule is `pending` or `in_progress`. A `completed` or `cancelled` schedule has nothing left to move * It still has a remaining deferred balance * It is not a point-in-time schedule. There is no spread to reshape * It does not use deferred discount recognition ## Export The **Export** dropdown on the **Revenue recognition** tab produces two XLSX reports. **Export waterfall** exports the matrix as displayed for the selected year: | Sheet | Contents | | - | - | | `Summary` | Totals for the selected year | | `Waterfall` | The booking-month × recognition-month matrix | | `Lines` | One row per invoice line item, so you can reconcile recognition entries against the underlying invoice lines | **Export recognized summary** exports recognized revenue only, cut three ways: | Sheet | Contents | | - | - | | `Summary` | Total recognized revenue for the period | | `By month` | Recognized revenue per month | | `By customer & product` | Recognized revenue broken down by customer and product | Every amount in the recognized summary carries an **`Origin`** column marking it `auto` (posted by the recognition engine) or `manual` (produced by an [adjustment](#adjust-remaining-recognition)). Exports run asynchronously. Hyperline notifies you in-app once the file is ready, and it will be available from **Exports** in the main navigation. # 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 type that matches a specific billing event. You can use filters to scope a rule to a subset of products, currencies, payment methods, or invoice custom properties. ## Rule types **Accounting** > **Settings** > **Rules** has four tabs, one per rule type: | Type | Trigger | What it controls | | - | - | - | | **Invoice posted** | An invoice is finalized 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 types can coexist in the same ledger. Hyperline resolves revenue recognition settings at invoice posting time alongside the **Invoice posted** rule. They are not triggered by a separate event. A fifth type, **accounting software sync**, exists but is not configured here. See [sync rules](#accounting-software-sync-rules) below. ## 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 type: **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 recognized) * Deferred revenue (until recognized) Beyond accounts, the **Revenue recognition** rule also carries the recognition behavior itself: * The **recognition method**: over time, point in time, or usage-based * The **granularity** (for over-time) or the **recognition date basis** (for point-in-time) * The **discount recognition mode**: immediate, deferred, or use net amount See [Revenue recognition](./revenue-recognition#recognition-methods) for what each of these does. ### Accounting software sync rules Accounting software sync rules map Hyperline billing records to the accounts expected by your connected accounting provider. When Hyperline sends a record to an external accounting provider, Hyperline converts the resolved account to the provider account code or internal account ID required by that provider. These rules are **not** configured on the accounting **Rules** page. Set them up under **Settings** > **Integrations**, on the connected provider. Available accounts and filters depend on the provider. For providers that support line-level account mapping, **Revenue account** on an invoice sync rule controls regular invoice and credit note lines. Providers that create a write-off record for uncollectible invoices use the **Write-off debit account**. Invoice sync rules can offer **Invoice type** (standard invoice vs custom document) and [custom property filters](#custom-property-filters), depending on the provider. Neither invoice type nor invoice custom property filters are offered on payment sync rules. For providers that support line-level account mapping, a line without a product gets its account from a sync rule only when a rule with a custom property filter matches it. Otherwise, the line keeps your accounting provider's default account. You can create accounts manually in Hyperline or fetch them from your accounting provider by syncing the ledger's chart of accounts. See [Chart of accounts](./accounts#sync-accounts-from-your-accounting-provider). ## View the rule tree Each tab of **Accounting** > **Settings** > **Rules** displays that type's rules as a tree, showing which rules would apply and in what order. This is useful for auditing your rule configuration before going live. Rules filtered on a custom property show as ` = ` branches. ## Filters You can scope rules using one or more filters. Available filters depend on the rule type. 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 type | Match standard invoices, custom documents, or both | | Custom properties | Match invoices by the value of an invoice custom property | | Accounting provider accounts | Match a connected accounting provider account | **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.) | | Bank accounts | Match by the bank account a payment was received on. Useful when you post settlements to different cash GL accounts per bank account. | | Currencies | Match transactions in a given currency | | Invoice type | Match standard invoices, custom documents, or both | | Custom properties | Match by the value of a custom property on the settled invoice | | Accounting provider accounts | Match a connected accounting provider account | **Credit note created** | Filter | Description | | - | - | | Products | Match specific products by ID | | Product types | Match by product type (`flat_fee`, `dynamic`, `addon`, `seat`, `one_off`, `credit`) | | Coupons | Match credit notes where the original invoice used a specific coupon | | Currencies | Match credit notes in a given currency | | Countries | Match customers billed from a given country | | Invoice type | Match standard invoices, custom documents, or both | | Custom properties | Match credit notes where the original invoice has a given custom property value | | Accounting provider accounts | Match a connected accounting provider account | **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) | | Invoice type | Match standard invoices, custom documents, or both | | Custom properties | Match invoices by the value of an invoice custom property | | Accounting provider accounts | Match a connected accounting provider account | An empty filter matches everything. Rules with no filters act as catch-all defaults. You can also scope rules to specific **customers**, but only through the API. Customer scoping is not offered in the rule form. ### Criteria reference The rule form can use the following criteria, depending on the selected rule type: | Criterion | Use it when | | - | - | | **Products** | A product needs its own revenue, deferred revenue, or provider account mapping. | | **Product types** | A whole product category should share the same mapping, such as all usage products. | | **Coupons** | Discounts or revenue should be mapped differently when a coupon is used. | | **Currencies** | Transactions in one currency should post to a different account. | | **Countries** | Billing from a country or jurisdiction needs a specific mapping. | | **Billing interval** | Monthly, quarterly, annual, or one-off charges need different account treatment. | | **Invoice type** | Standard invoices and custom documents need different account treatment. | | **Custom properties** | Invoices tagged with a custom property value, such as a business unit or fee type, should post to a different account. | | **Accounting provider accounts** | A rule should apply only to a specific connected accounting integration account. | | **Payment providers** | Settlements need different accounts depending on the payment provider. | | **Payment methods** | Settlements need different accounts depending on the method, such as card, SEPA direct debit, ACH, BACS, or bank transfer. | | **Bank accounts** | Payments received on different bank accounts should post to different cash accounts. | The **Invoice type** filter offers two values, **Invoice** (standard invoices) and **Document** (custom documents). A rule scoped to **Invoice** also applies to credit notes and refunds. Hyperline treats them as standard-invoice flavours. Leave the filter empty to match every invoice type. ### Custom property filters The **Custom properties** filter scopes a rule to invoices carrying a given [custom property](../properties/overview) value. Only custom properties available on the **invoice** entity are offered. The filter is also available on `invoice` [accounting software sync rules](#accounting-software-sync-rules). The value input follows the property type: * **Select, boolean, text, email, number, and date** properties take one value, and the invoice must have that value. Text and email matching is case-sensitive, so `test` doesn't match `Test`. * **Multi-select** properties take several values, and the rule matches when the invoice has at least one of them. When a rule filters on several properties, the invoice must match every one of them. An invoice with no value for a filtered property never matches. Properties marked as **API only** are not offered in the rule form, but you can still filter on them through the API. Each custom property counts as one more filter when Hyperline derives the rule [priority](#priority-and-fallback). On **Invoice settled** rules, the filter reads the settled invoice. You can't combine it with a **Payment clearing account**. Hyperline books payment provider payouts without the invoice, so they would never clear that account. You have an invoice custom property **Fee type** of type select, with the values `Subscription` and `Service`. You add an invoice posted rule filtered on **Fee type** = `Service`, mapping revenue to `4200 – Professional services`. Invoices tagged `Service` post their revenue to `4200`, and every other invoice keeps using your default revenue account. ## Priority and fallback Priority is **not something you set**. Hyperline derives it from how narrowly the rule is scoped (the more filters a rule carries, the higher its priority). It displays the resulting value read-only under **Advanced** in the rule form. When multiple rules match the same billing event, Hyperline applies them as a **priority overlay**: 1. Hyperline collects all matching rules and sorts them by priority (ascending) 2. Hyperline applies the rules in order: each rule overrides only the account roles it explicitly defines 3. For any given account role, the highest-priority rule that defines it wins In practice this means a broad catch-all rule acts as your default, and narrower rules override it for the specific cases they name. You get that behavior by scoping the rules, not by numbering them. You have a default invoice posted rule with no filters, mapping all revenue to account `4000 – Revenue`. You then add a second rule scoped to a specific product, mapping its revenue to `4100 – Usage Revenue`. The second rule is narrower, so it gets the higher priority. When an invoice is issued for that product, Hyperline uses `4100` for that product's line items and `4000` for everything else. ### Overlapping rules Specificity is scored against the **line actually being posted**, not against the rule in the abstract. A customer-scoped rule only outranks a product-scoped one when the line's customer is one of those the rule names. If it isn't, that rule doesn't match at all. When two rules end up equally specific for the same line, which one wins is **not** guaranteed. Distinguish overlapping rules by scoping them differently rather than relying on a tie-break. ## Add a rule Go to **Accounting** > **Settings** > **Rules**, open the tab for the event you want to cover, and click **Add rule**. 1. Select the **Rule type**. Note that **Invoice posted** appears as **Invoice issued** in this dropdown. They are the same thing. 2. Under **Applied on**, optionally add filters to scope the rule. 3. Under **Configuration**, map an account to each role. 4. **Advanced** shows the priority Hyperline derived from your filters. It is read-only. ## 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 click **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 database 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. Hyperline updates the dashboard data 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. You can filter this information by currency, invoicing entity, and date range. ### Live 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. The Dashboard chart is labelled **Live ARR** and shows the effective date next to the value. Hovering the title displays a tooltip that summarises the calculation and links to this section. Live ARR is a point-in-time metric derived from the **current state of active and pending subscriptions** and their consumption. Past or future phases and subscriptions are not taken into account. The value reflects a snapshot as of the effective date shown on the chart, so it fluctuates as subscriptions start, change, or cancel. 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. **Why Live ARR can differ from ARR at period end in [Insights](/docs/analytics/insights).** Live ARR reflects the current subscription state at the moment the Dashboard loads. ARR at period end is a monthly snapshot taken at the inclusive close of each period (the day before `periodEnd`). Between that closing date and now, subscriptions may have started, changed, or cancelled, so the two figures can legitimately show different numbers even for the same currency and entity. The number of customers reflects the total active subscribers contributing to ARR. 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 you 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 lets you 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 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 you 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 you 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 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 a custom date range. ### 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 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 because 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 a custom date range. Use the **Clear filters** button to reset customer and product filters. ### ARR at period end The **ARR at period end** chart plots the annualized recurring revenue at the close of each month in the selected date range. Each bar is a monthly snapshot. The summary value on the chart shows the closing date of the most recent bar (one day before the period's `periodEnd`, so the close is inclusive). Hovering the title displays a tooltip with the same summary and a link to this section. Use this chart to review how ARR evolved over time. Because each bar is a monthly close, the series is stable once a period ends and does not shift as new subscriptions or changes come in after the fact. The chart is broken down into: * **Committed revenue**: recurring revenue from booked subscription commitments in force at period end. * **Variable revenue**: usage-based charges attributable to the period. **Why ARR at period end can differ from Live ARR on the [Dashboard](/docs/analytics/dashboard).** ARR at period end is calculated from monthly subscription snapshots taken at the inclusive close of each period. Live ARR is the current active and pending subscription state at the moment the Dashboard loads. After the closing date, subscriptions may start, change, or cancel. Those movements only show up in Live ARR, not in the already-closed monthly snapshot. Both figures can be correct at the same time. ### 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. You can access reports from the dedicated **Reports** page in Hyperline. ## Available reports Hyperline offers a curated selection of reports essential for assessing various aspects of your company's financial health. You can view many reports directly in the platform with interactive filtering. All reports are also downloadable as CSV files, giving you convenient access to the data you need at any time. You can also export these reports using the [exports API](../../api-reference/endpoints/exports/create-export). ## Preview reports You can view many reports 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 * **Credit balances**: Monthly roll-forward of prepaid credit balances per customer and credit type ### 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, Hyperline automatically applies any active filters (customers, products, currencies, age buckets, invoicing entities, etc.) to the export. You can't export reports with more than 10,000 rows as CSV. Please narrow your date range or apply filters to reduce the number of rows. ## Exports history The **Exports** tab on the **Reports** page lists every export previously generated from your account, most recent first. Use it to find and re-download a file without re-running the export. Each row shows: * **Name**: the report or dataset the export was generated from * **Format**: the file format (`CSV`, `XLSX`, or `JSON`) * **Status**: the current state of the export * **Created**: the date and time the export was requested * **Download**: available once the export is ready An export moves through the following statuses: | Status | Meaning | | - | - | | `Pending` | The export has been requested and is queued | | `Processing` | The file is being generated | | `Done` | The file is ready to download | | `Failed` | The export could not be generated. Request a new one | The list refreshes automatically while an export is `Pending` or `Processing`, so the **Download** button appears as soon as the file is ready. Click **Download** to retrieve the file. Large exports are processed in the background. You can leave the page and come back to the **Exports** tab later to download the file once its status is `Done`. # 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 you can apply to a customer. In Hyperline, a coupon can reduce a charge by a fixed amount or by a percentage. You can reuse a coupon 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. Manage coupons from the catalog so your team can create them once, track them centrally, and apply them consistently. 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. | You can't edit the discount type and value after you create the coupon. 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. Select 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 You can apply coupons when creating or updating subscriptions, preparing quotes, and creating or editing invoices before they are finalized. When applying a coupon to a subscription or subscription quote, Hyperline asks how long the discount should apply and which eligible products should receive it. Select **All products** to apply it to every eligible product, or **Specific products** to select individual products. Product eligibility comes from the coupon settings, so you can only select products eligible for that coupon. For a manual invoice, you can select a catalog coupon or create an inline fixed-amount coupon for that invoice only. You select the invoice line items to discount without setting a subscription duration. Follow [Apply coupons to a manual invoice](../invoices/manage#apply-coupons) for the steps. ### Coupon duration When applying a coupon to a subscription, select 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 You create promotion codes 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 your team should apply the discount 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 You manage promotion codes 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 select 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. Hyperline shows an invalid code message and does not apply the discount if the code isn't eligible for the checkout. For example, the code may be expired, over its redemption limit, or restricted to another customer or product. ## 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 need to connect events first so Hyperline can detect usage data. ## Create a credit product To get started with credits, first create a credit product in your catalog, where you specify the events that rule the consumption. Hyperline then deducts credit usage automatically. 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. **Credit grant mode** controls how many credits are granted on a **partial period** (e.g. mid-cycle start, upgrade, or automated top-up at the end of a period): | Mode | Behavior | | - | - | | **Prorated** | Scale credits to the period, like billing (may be fractional). | | **Full allowance** | Always grant the full credits, even on a partial period. | This setting only affects the **credits granted**, not the invoiced amount. The invoice is always prorated for partial periods. With **Full allowance**, the customer pays a fractional price but receives the full credit allowance. **Create credit balance as soon as the product is added to a subscription** controls when the customer's balance starts existing. Keep it enabled for the usual case. Disable it when the balance must not consume events before the subscription is active. See [When the credit balance is created](#when-the-credit-balance-is-created). Select how the granted credit quantity determines the price: * **Volume pricing** applies progressive prices across quantity tiers. * **Bulk pricing** uses the tier reached by the total quantity to price all credits. * **Bundle pricing** offers predefined quantities at fixed prices. You can also select which bundles customers can purchase from the customer portal. When you assign the credit product to a plan or subscription, enter the quantity of credits to grant and select a catalog price. Hyperline calculates the resulting amount and stores it as a fixed fee on the subscription while retaining the selected pricing configuration as context. ## 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. You can also do this via the API. Here, you can also change the name and 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 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 You can add credit products created in the product catalog to predefined billing plans and subscriptions like any other product. You can also change options for this product at the customer/subscription level, allowing full customization without altering your catalog configuration. ## When the credit balance is created By default, Hyperline creates the customer's credit balance as soon as you add the credit product to a subscription. This includes draft subscriptions and quotes that have not been signed yet. From that moment the balance consumes reported events, and its starting balance accounts for the consumption your aggregators have already recorded. Disable **Create credit balance as soon as the product is added to a subscription** to delay this. The setting lives on the credit product in your catalog, and each subscription or quote can override it on its own credit product line. When it is disabled: * No balance exists while the subscription is a draft or the quote is unsigned, so nothing is consumed in the meantime. * On activation, the balance is created empty and the subscription's credit allowance is granted immediately, so the customer starts with exactly the quantity purchased. Consumption recorded before that point is ignored. Only events reported afterwards are deducted. * You can also create the balance yourself beforehand, for example to carry over the credits left on a previous batch. The allowance granted on activation is then added to that balance. A renewal is sold as a new credit product carrying 10,000 credits, and the quote is sent three weeks before the customer signs. With the setting disabled, no balance exists for that product while the quote is pending, so the usage reported during those three weeks is not charged against it. On signature, the subscription activates and the balance is credited with exactly 10,000 credits. On a partial first period, the quantity granted also depends on the **credit grant mode** of the product. Select **Full allowance** when the customer must receive the whole quantity purchased regardless of when the period starts. ## 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, Hyperline attributes the deducted amount to individual top-ups in **FIFO order by top-up creation date**. The oldest top-up is drained first and 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. As long as paid top-ups happen after that point, the allowance is consumed first. ## Real-time consumption and limits Credit balances are updated asynchronously when usage is reported through events. In production, balances can take about 60 seconds to reflect new consumption, because Hyperline intentionally buffers and processes usage in the background. Use the credit usage API endpoint (`POST /v1/customers/{id}/credits/{productId}/usage`) when you need to debit credits immediately from your own system. This synchronous debit flow is the right choice when you must enforce real-time limits, stop overconsumption, or block an action before confirming that the customer still has credits. Test and production environments can feel different for credit timing. Always validate real-time enforcement against the same environment your application will use. ## Credit expiration You can configure credits 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 top-up the credits will expire. ### Expiration at the end of the billing period You can configure credits 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 automatically expire when the billing period ends, and Hyperline adds new credits 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 top-up amount 2. Charge the customer's payment method 3. Add the credits to their balance ### Configuration options You can configure auto-topup 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. Hyperline automatically calculates the correct amount based on the bundle pricing. If you want to add 200 credits and your bundle is 50 credits for €400, Hyperline charges €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, Hyperline does not process the top-up and the balance remains unchanged. ## Credit balances report The **Credit balances** report gives you a month-by-month roll-forward of every prepaid credit balance, so finance teams can audit how credits were granted, consumed, and expired over time. You can view it on the [Reports](/docs/analytics/reports) page or export it through the [exports API](/api-reference/endpoints/exports/create-export) with `name` set to `credit_balances`. Each row covers one customer's balance for a single credit type and month. A customer can hold several balances in different units, and amounts are never combined across units. The report is dense: quiet months still appear, carrying the previous closing balance forward. A balance appears once it has had activity on or before the end of the selected period. Values are expressed in raw credit units (always positive), not in currency. | Column | Description | | - | - | | `Month` | Month covered by the row, in `YYYY-MM` format | | `Customer ID` | Identifier of the customer | | `Customer name` | Name of the customer | | `Credit balance ID` | Identifier of the credit balance | | `Credit type` | Credit product the balance belongs to | | `Unit` | Unit the credits are counted in | | `Opening` | Balance carried over from the previous month | | `Granted` | Credits added manually or as a complimentary grant | | `Purchased` | Credits bought as a one-off paid top-up | | `Subscription` | Credits granted by a subscription | | `Consumed` | Credits used through reported usage | | `Expired` | Credits removed when they reached their expiration | | `Adjustments` | Reconciling entry that makes the row balance | | `Closing` | Balance at the end of the month | Every row balances out: `Opening + Granted + Purchased + Subscription − Consumed − Expired + Adjustments = Closing` Months are bucketed in the customer's timezone, while the date-range filter bounds are interpreted in UTC. # Custom usage tracking Source: https://docs.hyperline.co/docs/customer-intelligence/custom-usage-tracking Assign usage aggregators directly to customers for monitoring and threshold alerts without creating a subscription or billing them. Custom usage tracking lets you assign usage aggregators directly to one customer, a set of customers or segments, or all customers. The metrics appear on customer pages without requiring a product or subscription and without affecting billing. Use it for metrics your team wants to watch at the account level, such as monthly active users, API calls, storage growth, seats provisioned, data processed, feature adoption, or plan-limit consumption. Directly assigning an aggregator to customers without a subscription is available with the [Customer Intelligence module](./overview). Standard usage-based billing does not include this direct assignment workflow. ## Direct assignment compared with subscription usage | | Aggregator used in a subscription | Aggregator assigned directly to customers | | - | - | - | | Setup | Link the aggregator to a product, then add the product to a subscription | Select customers or segments in the aggregator's **Visibility** settings | | Main purpose | Calculate billable usage or credit consumption | Monitor adoption, engagement, limits, or other customer signals | | Billing | Can affect invoices or credit balances | Never creates charges or invoice lines | | Period | Subscription metering period | Aggregator's default aggregation interval | | Module | Relevant billing feature | Customer Intelligence | ## How it works 1. You send usage events to Hyperline or load them through a connector. 2. An [aggregator](../usage/aggregators) turns those events into a metric. 3. The aggregator's **Visibility** setting assigns the metric to all customers or to selected customers and segments. 4. Assigned metrics appear on those customer records, on the customer overview and in the **Usage** tab. 5. Thresholds can alert your team when a customer's value crosses a configured limit. Custom usage tracking uses the same aggregator system as usage-based billing. If you need to create the underlying usage events first, start with [Send usage data](../usage/send-usage-data) or [Usage data with connectors](../usage/usage-data-with-connectors). ## Assign an aggregator to customers 1. Go to **Usage > Aggregators**. 2. Create a new aggregator or open an existing one. 3. Configure the metric: * **Name** * **Event type** * **Operation**: **Count**, **Sum**, or **SQL formula** * **Unit name** * Optional filters 4. In **Visibility**, select where the metric should appear: * **All customers** * **Specific segments and customers** * **No customers** 5. Set the default aggregation interval used to calculate the metric when no subscription provides a metering period. 6. Select the **Displayed value**: * **Total**: shows the total over the selected period. * **Last complete period**: shows the value from the last fully completed aggregation interval. 7. Add thresholds if you want to trigger alerts. 8. Click **Save changes**. ## Customer assignment options | **Visibility** option | Assignment behavior | | - | - | | **All customers** | The metric applies broadly, such as API calls for every account | | **Specific segments and customers** | The metric is only relevant for a cohort or handpicked accounts | | **No customers** | The aggregator is only used for billing, internal calculations, or another workflow | When using **Specific segments and customers**, add one or more customer or segment conditions. The metric appears on every customer record that matches at least one configured assignment. Selecting a visibility option only controls where the metric is monitored. It does not add the aggregator to a subscription or make the usage billable. ## Where usage appears Directly assigned aggregators appear in two places: * **Customer overview**: top usage metric cards summarize the most relevant customer-visible metrics. * **Usage tab**: the full list of visible usage cards includes charts, filters, thresholds, and event drill-downs. For the full customer usage workflow, see [Customer usage](../usage/customer-usage). In the **Usage** tab, you can change the period and grouping: | Grouping | Best for | | - | - | | **Monthly** | Long-term customer trends | | **Daily** | Weekly or monthly activity review | | **Hourly** | Intraday monitoring | Click **Explore** on a usage card to inspect the underlying events for that customer and metric. ## Use cases | Use case | Metric examples | What to watch for | | - | - | - | | Upsell opportunity | Seats provisioned, API calls, storage used, projects created | Customers approaching limits or growing steadily | | Add-on adoption | Premium feature events, advanced workflow usage, extra modules used | Customers getting value from features that map to paid add-ons | | Onboarding progress | First import, first integration sync, active users, key setup events | Customers that have not reached expected milestones | | Engagement risk | Active users, weekly activity, successful syncs, feature usage | Declining activity or no usage after purchase | | Usage overage review | Events above included allowance, credits consumed, peak usage | Customers likely to exceed contracted usage | | Capacity planning | Data processed, records stored, transactions created | Customers whose usage may require a plan or infrastructure review | ## Thresholds Thresholds let you alert on customer-level usage changes. A threshold can trigger when a value is greater than or equal to a limit, or less than or equal to a limit. Hyperline evaluates the threshold separately for each assigned customer, using the aggregator's default aggregation interval when there is no subscription. Crossing a threshold sends the configured alert; it does not create a charge, change a subscription, or update an invoice. Thresholds are useful for: * Usage spikes that may indicate overages * Usage drops that may indicate churn risk * Low adoption after onboarding * Customers approaching contractual limits * Customers reaching usage levels that may justify an upsell or add-on discussion You track monthly active users with an aggregator assigned to all customers. You set the displayed value to **Last complete period** and add a threshold for fewer than `20` active users. When a customer's active user count drops below that limit, your team can review the account before renewal. You track storage usage in GB and set a threshold at `800`. When the threshold is crossed, the customer owner can review whether the account is ready for a higher tier or an additional storage package. ## Related * [Aggregators](../usage/aggregators) * [Customer usage](../usage/customer-usage) * [Explore usage events and consumption](../usage/explore-usage-consumption) * [Customer monitoring agent](./customer-monitoring-agent) # Customer monitoring agent Source: https://docs.hyperline.co/docs/customer-intelligence/customer-monitoring-agent Configure the Hyperline customer monitoring agent to analyze account health, surface risk signals, and notify the right teammates automatically. The customer monitoring agent analyzes selected customers and produces a health score with supporting context. It helps you spot accounts that need attention because of payment issues, usage changes, support signals, contract risk, weak communication, or expansion potential. The agent benefits from Hyperline's revenue management context, including contracts, subscriptions, invoices, payments, and usage. This gives the health score a revenue-aware foundation. Connected tools such as Gmail, support platforms, meeting tools, and CRM systems then enrich it, along with built-in sources such as public company data. You can use one monitoring agent for your full customer base, or focus it on a specific [customer segment](../customers/segments) such as enterprise customers, customers near renewal, or customers with late payment behavior. ## Where to find it Go to **Customers > Monitoring** to create and manage monitoring agents. After an agent has analyzed a customer, the customer page can show: * A health score card on the customer overview * The last monitoring date * A link to the latest analysis * The monitoring agent assigned to that customer ## What the agent analyzes The agent combines billing and customer signals across several dimensions: | Dimension | What it considers | | - | - | | Payment health | Payment consistency, failed payments, disputes, and overdue invoices | | Usage and engagement | Product usage trends and declining activity | | Support signals | Recent ticket volume, sentiment, and frustration patterns | | Contract and valuation | Contract terms, renewal risk, and revenue at stake | | Communication | Meeting activity, email engagement, and relationship quality | | Public company data | Legal status, collective proceedings, establishment changes, and financial information for supported companies | For **Contract and valuation**, the agent can review the terms and attachments included with signed subscription quotes. It looks for conditions that could increase early churn risk, such as proof-of-concept, pilot, or trial periods; conditional exit or break clauses; termination for convenience; acceptance conditions; and exceptions to minimum commitments. When a signed quote or one of its attachments changes, the agent reviews the latest contract document again during its next analysis. Relevant conditions can appear in the health score reasoning and risk factors. Connected tools can add more context. For example: * Gmail and Outlook can add recent customer email threads. * Support tools can add ticket history. * Meeting tools can add summaries and transcripts. * CRM tools can add account records, deals, contacts, and notes. These dimensions are analysis angles, not a rigid checklist. Depending on the customer context, the agent can emphasize the most relevant angle, such as payment risk, billing issues, expansion readiness, renewal risk, weak communication, or unresolved support issues. ## How context is used in analysis During each run, Hyperline pulls the relevant context for each monitored customer from Hyperline and connected tools. The agent uses that context to explain the health score, not just to list recent activity. This helps the analysis connect signals that are often reviewed separately: * A late invoice can be interpreted with payment history, recent emails, open support threads, and renewal context. * A usage increase can be checked against CRM deal context and support sentiment to surface possible expansion readiness. * A usage drop can be compared with recent meetings, email silence, or unresolved support issues to identify churn risk. * A high-value customer can be prioritized differently when contract size, payment behavior, and relationship activity point in different directions. A customer has growing usage and an upcoming renewal, but recent Intercom conversations show unresolved implementation blockers. The agent can surface both the expansion signal and the risk, so the owner can prepare the right follow-up before starting a commercial conversation. ## Use cases | Use case | How the agent helps | | - | - | | Upsell and expansion review | Surfaces customers with strong usage, positive signals, and meaningful contract value | | Churn risk review | Highlights declining usage, weak engagement, negative support signals, or payment issues | | Renewal preparation | Summarizes health, risks, positive signals, and recent activity before renewal conversations | | Collections follow-up | Adds payment health and late invoice context to account-level monitoring | | Onboarding monitoring | Helps identify customers that have not reached expected usage or engagement milestones | | Executive account review | Gives account owners a concise health summary with supporting reasoning | ## Select a setup mode When you create a monitoring agent, select how much control you want over the analysis. | Mode | Best for | How it works | | - | - | - | | **Autopilot** | Quick setup or broad customer monitoring | Hyperline chooses the schedule and signal weighting based on billing data and connected tools | | **Advanced** | Specific monitoring playbooks, such as collections, renewals, or expansion reviews | Customer scope, schedule, fine tuning, context, connectors, and notifications | Use **Autopilot** when you want the agent to start monitoring with minimal setup. Use **Advanced** when you want to adapt the agent to a specific team workflow or customer segment. ## Create a monitoring agent 1. Go to **Customers > Monitoring**. 2. Click **Create agent**. 3. Open the agent and go to the **Configuration** tab. 4. Select **Autopilot** or **Advanced**. 5. Select which customers the agent monitors: * **All customers** * A specific customer segment 6. Click **Save changes**. When you change the monitored customer scope, Hyperline asks you to confirm the assignment changes. This helps prevent accidental changes when a segment includes a large number of customers. Use segments to keep an agent focused. For example, monitor "Enterprise customers renewing in the next 90 days" separately from lower-touch accounts. ## Fine tune the agent In **Advanced** mode, use the configuration tabs to customize how the agent works: | Setting | What it controls | | - | - | | **Customer scope** | Whether the agent monitors all customers or a selected customer segment | | **Schedule** | Whether the agent runs automatically or on a fixed schedule | | **Fine tuning** | How strongly each signal dimension contributes to the health score | | **Context** | Instructions the agent should use when interpreting customer signals | | **Connectors** | Connected tools the agent can use for CRM, support, meeting, or custom context | | **Notifications** | Who the agent can ping and which findings should trigger a notification | ### Configure schedule and scoring In **Advanced** mode, use **Schedule** to decide when the agent runs: * **Automatic**: Hyperline monitors customers when relevant events happen, such as new emails, late invoices, or usage changes. * **Fixed schedule**: the agent runs at a regular interval that you define. Use **Fine tuning** to adjust how strongly each dimension contributes to the health score. For example, you can give more importance to **Payment health** for collections-focused monitoring, to **Usage and engagement** for churn-risk monitoring, or to **Contract and valuation** for expansion and renewal reviews. ### Add context Use the **Context** tab to give the agent additional instructions: * **General context**: company or customer-base context the agent should know. * **Scoring instructions**: guidance for interpreting signals, such as industry-specific thresholds or risk rules. * **Include organisation hierarchy context**: include descendant customer context when the agent analyzes a parent customer. This is disabled by default. * **Hierarchy depth**: select whether to include descendants one, two, or three levels below the parent. This setting is available when organisation hierarchy context is enabled. Keep context concise and operational. The best instructions explain how your team interprets customer risk, not generic business goals. ### Analyze a parent with descendant context When **Include organisation hierarchy context** is enabled, the parent analysis can consider billing, usage, communications, risks, and value from descendant customers alongside the parent's own context. The agent keeps signals attributed to the relevant descendant and its path in the hierarchy. This option changes the context used for customer analysis only. It does not move subscriptions or invoices, combine billing data, or change the invoicing configuration defined through [organisation-based billing](../customers/organisation-based). An analysis can include up to three hierarchy levels and 50 descendants. If some descendant context is unavailable or the analysis reaches its context limit, the agent continues with the available information and does not treat missing data as a negative signal. ## Enable connectors Use the **Connectors** tab to select which data sources the agent can use. The tab can include CRM, support, meeting, built-in, and custom MCP data sources. Each available data source has a toggle. Third-party connectors appear disabled with **Connect to enable** until the underlying integration is connected. Built-in sources are available directly in Hyperline. Email context is handled separately. When **Gmail** or **Outlook** is connected for users in your workspace, the agent can use recent customer email threads for matching customer domains. These providers can appear in **Data sources** on an analysis result even though they are not toggled from the agent **Connectors** tab. Gmail, Outlook, Google Meet, and Granola are user-scoped: each teammate connects their own account from **Profile > Integrations** rather than the workspace-level **Settings > Integrations** page. See [Integrations overview](/integrations/overview) for the full connector catalogue. | Data source | Examples | What it adds | | - | - | - | | Email | Gmail, Outlook | Recent customer email threads, including subjects, participants, dates, and thread details when the agent needs communication context | | Support | Front, Help Scout, Intercom, Plain, Pylon, Zendesk | Support threads, statuses, priorities, labels, recent messages, and unresolved customer issues | | Call recording | Attio Call Recorder, Claap, Gong, Google Meet with Gemini, Grain, Granola, Jiminny, Modjo | Meeting records, participants, summaries, and transcripts when available | | CRM | Attio, HubSpot, Salesforce | Company records, contacts, deals, CRM meetings, and CRM notes | | Public company data | Pappers | French company identity, legal status, collective proceedings, establishment changes, financial information, and recent registry events | | Custom sources | MCP connections | Additional customer context from internal tools or custom data sources connected to the agent | ### Use Pappers company data Pappers is a built-in source for French public company data. When you enable **Pappers** from the agent's **Connectors** tab, Hyperline uses the company data available through Pappers to enrich monitoring runs. Hyperline identifies the company from the customer's **Registration number**. It accepts a SIREN or SIRET and falls back to a French **Tax ID** when the registration number is missing or invalid. If these identifiers are missing from a customer linked to an organisation, Hyperline can use the organisation's details instead. When a company is found, Pappers can add: * Whether the company is active or has ceased trading * Active or past collective proceedings, such as safeguard, receivership, or liquidation * Recently opened or closed establishments * Recent financial information, including revenue, results, and headcount when available * Recent public registry events This context can help the agent detect risks such as a new collective proceeding or opportunities such as a recently opened establishment. If no valid French company identifier is available, the company is not found, or Pappers is temporarily unavailable, the monitoring run continues with the other available sources. Keep customer **Domain** and **Billing email** values up to date. They help Hyperline match Gmail and Outlook messages, support threads, and meetings to the right customer. Before a renewal review, the agent can combine Hyperline billing data with Gmail threads, Intercom support conversations, Claap meeting summaries, and HubSpot deal context. The result helps the owner see payment risk, open support issues, recent engagement, and expansion signals in one customer health analysis. ## Configure notifications Use the **Notifications** tab to decide when and where the agent can ping your team. You can configure: * **Customer owner**: ping the user responsible for the monitored customer. * **Customer followers**: ping users following the customer. * **Specific people**: always ping selected users. * **Noise control**: only notify for findings at or above a selected severity. * **Slack threads**: post into a Slack channel when Slack is connected. For more about customer ownership and followers, see [Owner and followers](./owner-followers). Agent notification settings decide which recipients the agent may ping. Each recipient can also control their own channels and customer event subscriptions in **Profile > Notifications**. ## Run the agent manually You can trigger a manual run from the agent page, or from a customer health score card when a customer has not been monitored yet. When triggering a run, you can: 1. Select one or more customers. 2. Adjust scoring weights for that run. 3. Add one-time context for the analysis. 4. Start the run and open the run detail page. Manual runs are useful before a customer meeting, upsell review, renewal review, collections follow-up, or board reporting cycle. ## Read analysis results Each completed analysis can include: * Overall health score * Score tier * Short description * Reasoning * Dimension scores * Positive signals * Risk factors * Summary * Data sources and tools used | Score range | Tier | | - | - | | `0-25` | Critical | | `26-50` | At risk | | `51-75` | Needs attention | | `76-100` | Healthy | A health score is a prioritization signal. Use the reasoning, risk factors, and source data to decide what action to take. ## Related * [Customer intelligence overview](./overview) * [Owner and followers](./owner-followers) * [Custom usage tracking](./custom-usage-tracking) * [Late payment behavior](./late-payment-behavior) # Late payment behavior Source: https://docs.hyperline.co/docs/customer-intelligence/late-payment-behavior Use Hyperline's late payment behavior smart segment and payment metrics to identify at-risk customers and prioritize collections outreach. Late payment behavior helps you identify customers whose paid invoice history shows payment risk. It is available as a smart segment field in [customer segments](../customers/segments). Use it to prioritize collections, review payment terms, route manual follow-up, or focus a monitoring agent on customers with payment-risk patterns. ## How Hyperline evaluates late payments Hyperline computes payment behavior from settled invoices. For each paid invoice, Hyperline compares the settlement date with the expected payment date. The expected payment date is based on the invoice due date and the customer's payment terms. This avoids treating an invoice as late before the customer's configured payment delay has elapsed. The payment behavior metrics include: | Metric | Meaning | | - | - | | Paid invoices | Number of paid invoices considered for the customer | | Invoices paid after due date | Number of paid invoices settled after the expected payment date | | Late payment rate | Share of paid invoices that were paid late | | Average late payment delay | Average delay across invoices that were paid late | Late payment behavior is based on invoices that have been settled. Unpaid overdue invoices are still visible through invoice status, reminders, and other collection workflows. ## Smart segment: Late payment behavior Hyperline computes and maintains the **Late payment behavior** smart segment. You do not need to set a threshold yourself. Hyperline evaluates three signals together: * Whether the customer has paid invoices late * How often paid invoices are late * How long late invoices are delayed on average This keeps the segment focused on customers with meaningful late payment patterns instead of every customer with a single small delay. ## Create a late payment behavior segment 1. Go to **Customers > Segments**. 2. Click **New Segment**. 3. Enter a segment name, such as `Late payment behavior`. 4. Add a rule. 5. In the field picker, open **Payment behavior**. 6. Select **Late payment behavior**. 7. Preview the matching customers. 8. Click **Save**. Because this is a smart segment, selecting the field is enough. You do not need to select an operator or value. ## Build custom payment behavior rules If you want more control, use the numeric payment behavior fields instead of the smart segment. For example, you can combine: * **Late payment rate** is greater than or equal to `50` * **Average late payment delay** is greater than `10` * **Invoices paid after due date** is greater than or equal to `2` Use custom rules when you want to tune risk definitions for a specific collections process or customer cohort. You create a **High-risk payers** segment where **Late payment rate** is at least `50` and **Average late payment delay** is greater than `10` days. Your finance team follows the segment, and the monitoring agent watches it for new payment issues. ## What to do with the segment After saving the segment, you can: * Filter the customer list by the segment * Follow the segment to receive customer follower notifications * Use it as the customer scope for a monitoring agent * Review payment methods and invoice reminders for matching customers * Export matching customers for collections review ## Related * [Customer segments](../customers/segments) * [Customer monitoring agent](./customer-monitoring-agent) * [Owner and followers](./owner-followers) * [Invoice reminders](../invoices/reminders) # Customer intelligence Source: https://docs.hyperline.co/docs/customer-intelligence/overview Use Hyperline customer intelligence to monitor account health, usage trends, ownership, followers, and payment behavior signals in one place. Customer intelligence brings several customer-facing signals into one workflow. It helps you understand which customers need attention, who is responsible for them, how their usage is evolving, and where there may be risk or expansion potential. Customer Intelligence is a paid add-on. Contact the Hyperline team through the in-app chat to learn more or enable it for your account. Customer intelligence benefits from the same revenue management foundation that powers Hyperline contracts, subscriptions, invoicing, payments, and usage. This gives each analysis a revenue-aware starting point before external signals such as emails, support conversations, meetings, and CRM activity are added. Customer Intelligence can use context from the following sources: * **Hyperline**: Contracts, subscriptions, invoices, payments, and usage * **Public company data**: Pappers * **CRM**: Attio, HubSpot, and Salesforce * **Support**: Front, Help Scout, Intercom, Plain, Pylon, and Zendesk * **Email**: Gmail and Outlook * **Call recording**: Attio Call Recorder, Claap, Gong, Google Meet with Gemini, Grain, Granola, Jiminny, and Modjo Hyperline is continually adding new data sources. If a tool your team uses is not supported yet, contact the Hyperline team through the in-app chat and share what you would like to connect. Use it when your customer base is large enough that manual follow-up becomes hard to prioritize. Instead of checking customer records one by one, you can combine health monitoring, usage metrics, owner and follower assignments, and smart payment behavior segments. ## Buy vs build You can build customer intelligence internally, but the first obstacle is usually data access. Useful analysis needs the contract, subscription, invoice, payment, billing, usage, CRM, support, and communication context behind each customer. Recreating that context often means building data pipelines, matching customer records across tools, normalizing events, and maintaining the logic as your billing setup changes. Hyperline already manages the revenue foundation behind your customers. Customer intelligence can therefore start from the account's commercial reality, then add external signals from connected tools such as email, support, meetings, and CRM activity. This makes the analysis more practical: the agent can evaluate risk, expansion potential, renewal readiness, payment behavior, and usage adoption from the same place where your revenue operations already happen. | Common objection | What happens when you build | Why use Hyperline | | - | - | - | | "The data is already in a warehouse." | The warehouse can centralize data, but your team still needs customer matching, signal definitions, scoring, permissions, alerts, and account workflows. | Hyperline combines revenue context, monitoring, owners, followers, and notifications directly in the customer workflow. | | "A custom model would be more flexible." | Flexibility becomes maintenance when every new product, billing rule, segment, or renewal motion needs updates. | Monitoring agents can run on Autopilot or be fine-tuned with customer scopes, schedules, signal weights, connected data sources, and custom instructions. | | "CRM and support tools already show activity." | Activity signals are useful, but they often miss the commercial context: contract value, payment behavior, subscription state, invoice history, and usage trends. | Hyperline analyzes external activity alongside the billing and revenue data that explains the business impact of each signal. | | "Internal alerts are easy to add." | Alerts become noisy when they are detached from ownership, followers, customer segments, and the workflow for acting on them. | Hyperline routes customer intelligence to owners and followers so signals reach the people responsible for follow-up. | | "Building gives full control." | Full control also means owning integration drift, edge cases, permissions, auditability, and ongoing improvements. | Hyperline gives you a maintained system close to the source of revenue data, while still letting you customize how the agent monitors customers. | Build internally only when customer intelligence is a dedicated product your team wants to own end to end. For account prioritization, renewal preparation, expansion review, churn prevention, collections follow-up, and customer health monitoring, start with Hyperline. ## Multi-angle monitoring The customer monitoring agent reviews each customer from multiple angles, then emphasizes the signals that matter most for that customer context. It can look across payment, billing, usage, contract and renewal, communication, and support signals in the same analysis. This makes the health score more useful than a single rule or static checklist. For one customer, the main signal may be growing usage and expansion readiness. For another, it may be a late invoice combined with weak communication. For another, it may be an upcoming renewal with unresolved support issues. ## Setup and customization Create monitoring agents from **Customers > Monitoring**. You can start with **Autopilot** when you want Hyperline to choose the schedule and signal weighting, or use **Advanced** mode when your team has a more specific monitoring playbook. In **Advanced** mode, you can select the monitored customer scope and schedule, fine-tune signal weights, add scoring instructions, enable connected data sources, and configure who should be notified. ## Capabilities Monitor customer health from multiple angles with Autopilot or fine-tuned agent settings. Display custom usage metrics on customer pages and alert on threshold crossings. Assign a responsible owner and let teammates follow customers or customer segments. Identify customers with late payment patterns using smart customer segments. ## How the signals work together | Signal | Where it appears | How you can use it | | - | - | - | | Monitoring health score | Customer overview and monitoring analysis pages | Prioritize churn risk, payment anomalies, expansion signals, and accounts that need review | | Custom usage metrics | Customer overview and **Usage** tab | Track engagement, adoption, capacity growth, or product consumption outside standard billing views | | Owner | Customer overview | Route accountability and monitoring agent pings to the responsible user | | Followers | Customer overview and segment follow actions | Keep interested teammates subscribed to customer updates | | Late payment behavior | Customer segments | Build payment-risk cohorts for collections, stricter terms, or manual outreach | ## Common workflows * **Monitor strategic accounts**: create a segment for key customers, assign owners, then configure a monitoring agent to watch that segment. * **Identify upsell opportunities**: expose usage metrics such as seats, API volume, storage, or feature adoption, then create segments for customers approaching plan limits or showing sustained growth. * **Prepare renewals**: review customer health, payment behavior, usage trends, and recent positive signals before renewal conversations. * **Improve onboarding**: track early usage milestones and follow customers that have not adopted key features after contract signature. * **Detect product expansion**: monitor customers using a feature heavily, consuming multiple add-ons, or growing usage across teams. * **Track engagement risk**: expose usage aggregators on customer pages, add thresholds, and use monitoring analysis to interpret declining usage. * **Improve collections follow-up**: create a segment using **Late payment behavior**, follow the segment, and notify owners or followers when the monitoring agent detects new payment issues. * **Coordinate account work**: use followers for teammates who should stay informed even when they are not the primary customer owner. ## Use case examples | Use case | Signals to combine | Typical action | | - | - | - | | Upsell readiness | High or growing usage, healthy monitoring score, active communication | Ask the owner to review plan limits, add-ons, or a higher tier | | Churn prevention | Declining usage, low health score, support frustration, weak communication | Create a follow-up task or prepare an account review | | Renewal preparation | Contract timing, usage history, payment behavior, positive and risk signals | Review the account before commercial discussions | | Onboarding follow-up | Low usage after subscription start, missing milestone events | Notify the owner or customer success team | | Collections prioritization | Late payment behavior, overdue invoices, owner and followers | Route follow-up to finance and the account owner | | Customer segmentation | Usage, billing, payment behavior, custom properties | Build dynamic customer cohorts for reporting or team workflows | Some customer intelligence capabilities may depend on your account configuration and user permissions. If you do not see a page or setting described here, contact the Hyperline team via the in-app chat. ## Related * [Customers](../customers/overview) * [Customer segments](../customers/segments) * [Customer usage](../usage/customer-usage) * [Aggregators](../usage/aggregators) # Owner and followers Source: https://docs.hyperline.co/docs/customer-intelligence/owner-followers Assign a customer owner, follow customers or segments, and route Hyperline monitoring notifications using owner and follower signals. Customer owners and followers help you route accountability and notifications to the right people. * **Owner**: the user responsible for the customer. * **Followers**: users who want to stay informed about a customer, even if they are not the owner. The customer monitoring agent can use both fields when deciding who to ping about a customer. ## Where owners and followers appear Open a customer page and view the customer information panel. When customer intelligence is enabled, you can see: * **Owner**: an inline user selector. * **Followers**: follower avatars and a **Follow** or **Unfollow** action. * **Monitoring agent**: the agent currently monitoring the customer, if one is assigned. ## Set or change the customer owner 1. Open the customer page. 2. Find the **Owner** row in the customer information panel. 3. Select a user from the dropdown. 4. Hyperline saves the owner and shows a confirmation message. You can clear the owner if no user should be responsible for that customer yet. Use one owner per customer for accountability. Use followers for teammates who need updates but should not be treated as the primary owner. ## Follow or unfollow a customer 1. Open the customer page. 2. Find the **Followers** row. 3. Click **Follow** to follow the customer. 4. Click **Unfollow** to stop following the customer. The owner can also follow the customer. Ownership and following are separate signals. ## Follow a customer segment You can follow a segment to automatically follow every customer that belongs to it. 1. Go to **Customers > Segments**. 2. Open a segment. 3. Click **Follow segment**. When a customer matches a followed segment, Hyperline adds you as a follower through that segment. If the customer later stops matching the segment, Hyperline removes the segment-based follow automatically. If you follow a customer through a segment, you cannot unfollow that customer individually while the segment still applies. To stop those follows, unfollow the segment or update the segment rules. ## Use owners and followers for notifications In a monitoring agent's **Notifications** tab, you can select whether the agent may ping: * The **Customer owner** * **Customer followers** * Specific selected users * A Slack channel Hyperline deduplicates recipients when the same user is both an owner and a follower. ## Configure your profile notifications You control your personal notification preferences from **Profile > Notifications**. These settings apply when you are selected as a customer owner or follower for a customer notification. The profile notification page has three main areas: | Area | What you can configure | | - | - | | **Notification channels** | Which personal channels Hyperline can use to notify you | | **Customer notifications** | Which customer events should trigger notifications for you | | **Followed segments** | Which segments automatically add you as a follower on matching customers | ### Notification channels Use **Notification channels** to decide where you can receive agent pings: * **Hyperline chat**: creates an in-product conversation when an agent pings you. * **Slack DM**: sends agent pings to you directly in Slack when Slack is connected. * **Email**: sends agent pings by email when email delivery is available for your account. Slack DM and email options may appear unavailable until the related provider is connected. ### Customer notifications Use **Customer notifications** to select which customer events should notify you when you are the owner or a follower of the customer. You can enable or disable: * **Invoice settled** * **Invoice becomes late** * **Payment fails** * **Payment method changes** * **Payment method deleted** * **Monitoring score changes** * **Contract renews soon** For **Monitoring score changes**, set the minimum score change required before Hyperline notifies you. For **Contract renews soon**, set how many days before renewal you want the notification to trigger. ### Followed segments Use **Followed segments** to manage segment-based follows from your profile. 1. Go to **Profile > Notifications**. 2. In **Followed segments**, select a segment. 3. Click **Add**. You automatically follow customers matching that segment. You can also remove a segment from this list to stop following customers through that segment. Combine segment follows with customer notification settings to build personal work queues. For example, follow a **Late payment behavior** segment and enable **Invoice becomes late** to stay informed about customers that match your collections scope. Your finance lead follows a **Late payment behavior** segment, while account managers are assigned as owners on their customers. When the monitoring agent detects a payment issue, it can notify the owner for accountability and the finance lead for collections context. ## Related * [Customer monitoring agent](./customer-monitoring-agent) * [Customer segments](../customers/segments) * [Late payment behavior](./late-payment-behavior) # How the customer balance is calculated Source: https://docs.hyperline.co/docs/customers/balance Learn how Hyperline calculates a customer account balance from outstanding invoices, credit notes, and wallet credit, and how to read it. Every customer has an **account balance** that summarises their financial position with you at a glance. It appears on the customer overview page and answers a single question: does this customer owe you money, or are they in credit? ## Reading the balance card The balance is shown as a card at the top of the customer overview page. Its **color** is an at-a-glance signal of whether the customer needs attention, and the **tag** underneath spells out why. Customer overview page with the balance card at the top left ### What the colors mean | Card color | Tag | What it means | | - | - | - | | 🔴 **Red** | `{n} late` | At least one outstanding invoice is **overdue** (past its due date). Payment is late and likely needs chasing. | | 🟡 **Yellow** | `{n} outstanding invoices` | The customer has unpaid invoices, but **none are overdue yet**; they are still within their payment terms. | | ⚪ **Neutral** | `In credit` | No outstanding invoices, and the balance is positive: credit notes and wallet credit exceed what the customer owes. | | ⚪ **Neutral** | `All clear` | No outstanding invoices and a settled, zero balance. | The difference between **red and yellow** is purely about timing. As soon as a single open invoice passes its due date, the card turns red. It stays yellow while every open invoice is still within terms. A customer can move from yellow to red without any new invoices, simply because a due date has passed. The color and tag are driven only by the customer's open invoices, independently of the headline amount. So the card can stay yellow or red even when the amount itself shows a dash (see [the currency shown on the card](#the-currency-shown-on-the-card)). Red balance card with a late invoices tag Yellow balance card with an outstanding invoices tag Neutral balance card with an in credit tag Neutral balance card with an all clear tag ## The formula The balance combines three components: ``` Balance = unpaid credit notes + wallet credit − outstanding invoices ``` The sign tells you the direction: * **Negative**: the customer **owes** you money (their outstanding invoices exceed their credit). * **Positive**: the customer is **in credit** (their credit notes and wallet exceed what they owe). * **Zero**: the account is fully settled. ## The three components ### Outstanding invoices The total still due on the customer's **finalized** invoices that are not yet fully paid, including partially paid and failed ones. This is the only component that pushes the balance towards "owing". Hyperline doesn't count draft, voided, fully paid, or refunded invoices. It also excludes an invoice with a payment in progress until that payment settles or fails. ### Credit notes The total of [credit notes](../invoices/refunds) issued to the customer that have not yet been refunded or applied to an invoice. Once a credit note is applied to an invoice, it reduces that invoice's amount due, so it is never counted twice. ### Wallet credit The customer's available [prepaid wallet balance](../wallets/balance). A wallet balance only ever increases credit; it is never treated as negative. An unallocated payment transaction is not part of the wallet balance and does not settle an invoice by itself. It affects the customer's position only after you allocate it to an invoice or add it to the wallet. See [Understand payment allocations](/docs/payments/allocations#transactions-unallocated-funds-and-wallets). ## A worked example | Component | Amount | | - | - | | Outstanding invoices | 10,000 | | Credit notes | 3,000 | | Wallet credit | 1,500 | | **Balance** | **−5,500** | `3,000 + 1,500 − 10,000 = −5,500` → the customer **owes 5,500**. If the same customer instead had no outstanding invoices, the balance would be `3,000 + 1,500 = +4,500`, meaning they are **4,500 in credit**. ## The currency shown on the card The balance card always shows the figure in the **customer's own currency** (the currency set on the customer record), with no conversion. A customer can still have invoices, credit notes, or wallets in other currencies; Hyperline tracks each currency separately. The card reflects only the customer-currency balance, so activity in other currencies is not folded into the headline figure. If a customer has no balance activity in their own currency (for example, all of their invoices are in a different currency), the amount shows as a dash (such as `- €`). The card color and invoice-count tag still reflect their open invoices. ## Organisations and child customers For a parent customer in an [organisation](../customers/organisation-based), you can switch to the **aggregated view** to see the combined balance of the parent and all of its child customers. Hyperline shows this balance in the parent's currency. Invoices that have already been consolidated onto the parent are counted once, so a charge is never double-counted across the parent and its children. # 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 you click the export button, Hyperline compiles your customer data into a CSV file. Download the file to access a complete export, including customer details, their number of active subscriptions, estimated ARR, and more. ## Large exports Hyperline generates customer exports asynchronously. On large workspaces, the file can take longer to prepare before it is available to download. CSV exports are limited to 10,000 rows. If your workspace has more customers than the export can include, you have three options. Narrow the data before exporting, use the public API for paginated extraction, or contact support for help with a bulk export. For recurring reporting needs, consider [automated exports](../analytics/automated-exports) instead of manual CSV downloads. # 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. For usage-based subscriptions owned by the parent, you can also include direct child customers' usage in a metered product. See [Include child customers' usage](../subscriptions/metering#include-child-customers-usage). If you use Customer Intelligence, a monitoring agent can optionally include descendant customer context when analyzing a parent customer. This affects the health analysis only and does not change invoice routing or organisation-based billing settings. See [Analyze a parent with descendant context](../customer-intelligence/customer-monitoring-agent#analyze-a-parent-with-descendant-context). ## Activate organisation-based billing Here, you can see the parent/children relationship and the invoicing configuration for this customer. Click **Set parent organisation** to select a parent organisation for this customer. You'll be prompted to select 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 customer's invoices as pending and concatenate them regularly with other children from the parent. Concatenated invoices will display one line item per child invoice with the original line items listed in the description. * `No change` will attach the child to the parent but will not change any invoicing parameter. If you selected `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 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, Hyperline automates everything, 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 appears on the invoicing section of the children to inform you that Hyperline bills the invoices 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, Hyperline 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, Hyperline creates the parent invoice as a draft. * For `Grouped` configuration: if any child subscription has draft invoices enabled, Hyperline creates the merged parent invoice 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. **Consumption exports** When child invoices are charged to the parent, exports can include the child usage and machine-level consumption data. However, they do not expose a per-line euro amount for each child consumption line. Use the parent invoice lines for the billed amounts and the consumption export for the underlying usage detail. **Invoices that can't be grouped** For `Grouped` configuration, a child invoice can only be rolled up onto the parent if its invoicing entity matches the parent's. When it doesn't, Hyperline blocks the regroup for that invoice and surfaces a red callout on both the parent and the child customer overview. The callout links to a Sentinel task listing the affected invoices. Review them and align both the invoice's invoicing entity and the customer's invoicing entity with the parent's. Once aligned, the invoice becomes eligible for regrouping again. **Remove a child company from its parent** In the modal where you linked the child company to its parent, a red button has appeared. Click this button to remove the child company from the parent. Any future invoice then stays 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. Create a customer in Hyperline as soon as they register for your product. Customer intelligence is available from customer records to monitor health, usage trends, ownership, followers, and payment behavior. See [Customer intelligence](../customer-intelligence/overview). ## 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 is required; Hyperline can infer currency and country from your billing settings. The customer appears 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 You can create customers programmatically [using the API](../../api-reference/endpoints/customers/create-customer). Additionally, when a CRM is connected and configured to automatically sync customers to Hyperline, Hyperline creates customers automatically. If CRM records are duplicated, linked to the wrong customer, or not updated as expected, see [Understand CRM sync matching](../../guides/crm-sync-matching). ### Default language, country, and currency When you create a customer, Hyperline determines the language through a cascade. If you provide a language explicitly, Hyperline uses that value. Otherwise, if you provide a country, Hyperline infers the language from that country. If you provide neither, the language defaults to the invoicing entity's language. The country follows a simpler fallback: Hyperline uses the provided country if available; otherwise, it defaults to the invoicing entity's country. The currency also follows a fallback cascade. If you provide a currency explicitly, Hyperline uses that currency. Otherwise, if you provide a customer country, Hyperline infers the currency from that country. If you provide neither, the currency defaults to the invoicing entity's currency. This ensures that every customer has valid language, country, and currency settings, even when not explicitly specified. ## Edit a customer You can update customer information at any time by clicking **Edit** in the actions dropdown. You can't change the **currency** 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 (you must manage the currency in the external tool) If you need to change the currency and cannot do so, please contact support. ### Force draft invoices The **Force draft invoices** setting on the customer forces every invoice generated for that customer to be created as a `draft`. This lets you review and validate it manually before it's sent. Enable it from the customer's edit page by toggling **Force draft invoices** on. It applies to all invoices generated for the customer: subscriptions, one-off invoices, and parent invoices in [organisation-based billing](/docs/customers/organisation-based) or [consolidated invoicing](/docs/invoices/consolidated-invoicing). This customer-level setting overrides the subscription-level **Generate draft invoices** option. When it is enabled, invoices land in `draft` even if their subscription is not configured to draft invoices, and even after a [grace period](/docs/invoices/term) ends. ### 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 identifier** is enabled in the invoicing entity's tax settings, company customers must provide a Tax ID. When local tax numbers are enabled, they can provide a local tax number instead. ### Tax identifiers A company customer can have two tax identifiers: * **Tax ID**: The primary tax identifier, such as an EU VAT number. Hyperline uses this value for tax calculation, validation, and reverse charge rules. * **Local tax number**: A country-specific identifier used for local invoicing or reporting requirements. Hyperline does not validate this value through VIES or use it to determine reverse charge eligibility. To collect local tax numbers for customers linked to an invoicing entity, go to **Settings** > **Taxes** for that entity and enable **Enable local tax number**. The field then appears when you create or edit company customers and in customer billing forms on hosted pages. ### Tax ID validation Customer tax IDs show a validation status on the customer page. For EU VAT numbers, Hyperline validates the number through the EU VAT Information Exchange System (VIES) and stores the consultation number when available. The main statuses are `valid`, `invalid`, `mismatch`, `unverified`, and `unsupported`. See [Tax ID validation](../invoices/tax-management#tax-id-validation) for the full status reference and the related invoicing entity enforcement settings. ### French tax IDs and registration numbers For French customers, Hyperline can use the **Registration number** field, which may be a SIREN or SIRET, to prefill the customer's **Tax ID**. If the tax ID is empty and you enter a valid French registration number, Hyperline derives the French VAT number automatically. If you provide both values, Hyperline keeps the tax ID and registration number as entered, even if they do not match. This lets you save the customer details first and review the values later from the tax ID validation status. When a tax ID was previously inferred from a French registration number, updating the registration number refreshes the inferred tax ID. Tax IDs that were explicitly entered are preserved. ## Addresses ### Billing address You can save one billing address per customer to display on quotes and invoices. You can add or edit it in the customer's details. Hyperline also uses it as the shipping destination unless you select a separate shipping address. ### Shipping address You must enable shipping details for the customer's [invoicing entity](/docs/account/invoicing-entities) before shipping controls are available. You can save multiple shipping addresses for a customer while keeping one billing address. For example, you can save a customer's head office and regional offices, then select which location to use for each subscription. #### Manage saved addresses Open the customer's details to add or edit shipping addresses. Each saved address is managed separately. Adding an address does not automatically make it the customer's shipping destination. #### Select the default destination By default, Hyperline uses the billing address as the shipping destination. You can instead select a saved shipping address as the customer's default destination. Switching back to the billing address preserves the saved shipping addresses. Selecting a different destination does not edit those addresses or change existing invoices. Subscriptions without a specific shipping address follow this customer destination. A [subscription-specific address](/docs/subscriptions/update#shipping-address) takes precedence, so changing the customer's default does not change that subscription's selection. #### Customer portal and documents When shipping details are enabled, customers can edit their shipping address directly from the customer portal. You can also display shipping details on quotes and invoices. #### Delete a shipping address Before deleting a shipping address: * If it is the customer's selected shipping destination, select another saved address or switch to the billing address first. * If a subscription references it, change or clear the selection on every subscription that uses it first. Deleting an address never selects a replacement destination automatically. Existing invoices keep their recorded address. 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. The portal gives your customers a transparent and well-organized billing summary. As well as displaying information correctly, this portal offers a number of action options for your customers: #### Portal language Hyperline selects the portal language using these rules: * If the customer's browser language is part of the 8 supported languages (English, French, German, Italian, Spanish, Polish, Portuguese and Dutch), the portal displays in that language. * If it is not part of the supported languages, Hyperline defaults to 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 **Subscription details** on the portal. This sub-page displays the content of the next invoice that will be billed, as well as the detailed price structure of every product. #### Change payment method Customers can change their payment method by clicking the trash button next to their current payment method and adding the new one. #### Top-up wallet You can make your customers autonomous by letting them top up their wallet in the portal. For this, make sure you enable the option on the wallet settings first. Clicking **Top-up wallet** on this screen triggers an immediate payment from the registered credit card and credits the wallet instantly. #### Edit billing information Customers can update their billing details by clicking the **Edit** button. This keeps their billing information accurate and up to date. You can control this capability in **Settings > Hosted pages**. See the [Billing details update](#billing-details-update) section below for more details. #### Download invoices The portal lists all invoices, and customers can open each one on its dedicated [invoice page](../invoices/invoice-page). Customers can download their invoice PDF using the **Download** button in 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 **Portal**. 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 you configured in **Settings** 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 This domain controls the URLs of your hosted pages. To send customer emails from your own domain, configure a [custom sending domain](../account/emails#custom-sending-domain) in **Settings > Emailing > Sending**. To further personalize 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). To enable it, add a `CNAME` record pointing to `cname.hyperline.co` on your DNS provider. For example, if you set your custom domain to `billing.alpeak.com` in Hyperline and add the related `CNAME` record on your DNS provider, your portal and checkout URLs take this form: ``` https://billing.alpeak.com/portal/:customerId https://billing.alpeak.com/checkout/:sessionId ``` Hyperline automatically manages 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 on hosted pages. These details include billing address, billing email, tax identifiers, and invoice emails. In **Settings > Hosted pages**, under the **Customer actions** section, toggle **Allow billing details update** to enable or disable this capability. When enabled, customers can edit their billing information through the customer portal, checkout, and quote pages. The **Local tax number** field is available for company customers when it is enabled in the invoicing entity's **Taxes** settings. #### 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 can't change their typology on hosted pages, and the form uses 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. Customers can always delete non-default payment methods, 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. The customer needs to retry or re-authenticate rather than delete the payment method. ### Display options You can control what subscription information is displayed on hosted pages through **Settings > Hosted pages** under the **Display** section. #### Hide contract duration By default, subscription pages show contract details such as the contract start, commitment duration, and renewal terms. Toggle **Hide contract duration** in **Settings > Hosted pages** under the **Display** section to hide these details from the customer portal. Enable it when contract terms are managed outside Hyperline or could confuse customers. ### 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. Hyperline sends a magic link 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. This is 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**: links work for the configured window. After expiry, the portal shows a link-expired page, without a login screen. Customers need a new link to access it. * **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. This is useful when you send links 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. Here's how it looks in the portal. ### Display personalization To hide the sidebar, add the `&hideSidebar=true` query parameter to your portal URL. The portal looks like this: This works for both 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 ` ``` Browsers block payment features (Apple Pay, Google Pay) inside third-party iframes unless the embedding page explicitly delegates the `payment` permission. Without this attribute, wallet payment buttons don't appear for your customers. Card payments still work. This also applies if you embed Hyperline checkout, quote, or payment pages in an iframe. If you use the [React SDK](/developers/react-components), the permission is set automatically. Make sure you run a recent version of `@hyperline/react-components`. If your site uses a strict Content Security Policy (CSP), you must explicitly allow Hyperline's domains: ```html theme={null} ``` Add the following origins to your CSP so the iframe can load and downloads work: Production * [https://app.hyperline.co](https://app.hyperline.co) (Portal UI) * [https://internal.hyperline.co](https://internal.hyperline.co) (API calls within the iframe) * [https://api.hyperline.co](https://api.hyperline.co) (Public API calls) Sandbox * [https://sandbox.app.hyperline.co](https://sandbox.app.hyperline.co) * [https://sandbox.api.hyperline.co](https://sandbox.api.hyperline.co) * [https://sandbox.internal.hyperline.co](https://sandbox.internal.hyperline.co) If you’re using a custom domain for hosted pages, also include that domain wherever you allow app.hyperline.co. # Customer segments Source: https://docs.hyperline.co/docs/customers/segments Group Hyperline customers into dynamic segments using rule-based filters on country, currency, subscription status, custom properties, and more. Customer segments let you slice your customer base into dynamic, rule-based groups, for example "Enterprise customers in France paying by direct debit" or "All customers with a parent company". As your billing operations scale, treating every customer the same becomes impractical. Segments give your finance and revenue teams a way to define cohorts based on billing attributes (country, currency, payment method, invoicing entity, custom properties, etc.). You can then instantly see which customers fall into each group. Unlike static tags or manual lists, segments are **evaluated continuously**: when a customer's data changes, their segment membership updates automatically. Common use cases include: * **Regional billing analysis**: group customers by country or currency to review revenue distribution across markets. * **Payment method monitoring**: identify customers without a payment method on file or those using a specific gateway. * **Payment risk and collections**: surface customers who pay late often, have a high average delay, or whose payment method is errored or expired. * **Entity-level reporting**: filter customers by invoicing entity for compliance or accounting purposes. * **Custom cohorts**: combine custom properties with standard fields to build segments that match your business logic, such as plan tier, industry vertical, or contract type. * **Handpicked lists**: add a condition on specific customer IDs to build a segment from an explicit list of customers, useful when no shared attribute can define the group. ## Manage segments ### Create a segment Navigate to the **Segments** tab and click **New Segment**. Enter a **name** and an optional **description** for the segment. A segment is made of one or more **rules**, each containing one or more **conditions**. * Conditions within a rule are combined with **AND** logic: a customer must match all conditions in the rule. * Multiple rules are combined with **OR** logic: a customer belongs to the segment if they match any rule. Each condition is defined by a **field**, an **operator**, and one or more **values**. The field picker is organized into four sections to help you find the right attribute: * **Customer**: identity and account attributes (country, currency, language, invoicing entity, tax ID, etc.). * **Payment behavior**: payment method and collection metrics, including the **Late payment behavior** smart segment (see below). * **Billing**: subscription, product, and invoice attributes. * **Custom fields**: any text, email, number, select, or boolean custom property defined on customers. As you build your rules, a **live preview** table shows matching customers in real time. The table is paginated and searchable, and its columns dynamically adapt to display the fields used in your conditions. Click **Save** to create the segment. It immediately appears in the segment list with its customer count. ### Edit a segment You can edit any segment by clicking it in the list. The same form opens inline. Update rules, conditions, or details, and save directly without a modal. The live preview updates as you modify the rules, so you can see the impact of your changes before saving. ### Delete a segment To delete a segment, open the actions menu and click **Delete**. A confirmation modal appears. Deletion is permanent and cannot be undone. ## Available filter fields | Section | Field | Value type | | - | - | - | | Customer | Customer | Multi-select (search and select specific customers) | | Customer | Country | Multi-select (country list) | | Customer | Currency | Multi-select (currency list) | | Customer | Language | Multi-select (language list) | | Customer | Invoicing entity | Multi-select (your invoicing entities) | | Customer | Relationship | Has parent / Has child | | Customer | Tax ID | Presence only | | Customer | External ID | Presence only | | Payment behavior | Late payment behavior | Smart segment (Hyperline-managed, see below) | | Payment behavior | Payment method type | Multi-select (card, direct debit, etc.) | | Payment behavior | Payment method status | Multi-select (Active, Pending, Errored, Expired) | | Payment behavior | Paid invoices | Number (count of paid invoices) | | Payment behavior | Invoices paid after due date | Number (count of invoices paid late) | | Payment behavior | Late payment rate | Number (share of invoices paid late, as a percentage) | | Payment behavior | Average late payment delay | Number (average days past due across late payments) | | Billing | Subscription status | Multi-select | | Billing | Subscribed product | Multi-select | | Billing | Invoice status | Multi-select | | Custom fields | Custom properties | Depends on the property type (text, email, number, select, boolean) | ### Smart segments Smart segments are cohorts **computed and maintained by Hyperline** from your billing data. You don't have to define their criteria yourself. They appear in the **Payment behavior** section of the field picker, marked with a lightning icon. * **Late payment behavior**: customers Hyperline identifies as showing late payment patterns, based on their paid and overdue invoice history. Add this field to a rule to target at-risk customers for dunning campaigns, manual outreach, or stricter payment terms, without having to tune the underlying thresholds yourself. Smart segments don't take an operator or a value. Selecting the field is enough. ### Operators The operators available on a condition depend on the field type: * **Text and multi-select fields** (country, currency, payment method type, payment method status, subscription status, etc.): `is in`, `is not in`. * **Presence-only fields** (Tax ID, External ID): `is set`, `is not set`. * **Date fields** (created at, contract end date, etc.): `is after`, `is before`, `is between`. * **Numeric payment behavior metrics** (paid invoices, invoices paid after due date, late payment rate, average late payment delay): `equals`, `is greater than`, `is greater than or equal to`, `is less than`, `is less than or equal to`, `is between`. For example, to build a "high-risk payers" segment you could combine `Late payment rate is greater than or equal to 50` with `Average late payment delay is greater than 10` in a single rule. ## Segment stats The segment list displays stats for each segment: * **Customer count**: the number of customers matching the segment's rules * **Percentage**: the share of your total customer base that belongs to the segment These stats are kept up to date as your customer data evolves. ## Filter the customer list by segment Once you have created segments, they become available as filters in the main **Customers** list. Select a segment from the filter dropdown to narrow the list to only the customers that belong to that segment. This makes it easy to quickly navigate to a specific cohort without leaving the customer list. For example, you can review all customers in a given country or all customers using a particular payment method. # Feature entitlements Source: https://docs.hyperline.co/docs/entitlements/overview Manage product capabilities, feature flags, and usage limits in Hyperline with catalog features, product grants, and per-customer overrides. Features represent the product capabilities, access rights, or usage limits that customers receive outside of billing. They help your team track what each customer is entitled to use, based on the products they have and any customer-specific override. Use features when you need to manage access such as SSO, premium integrations, included seats, API limits, or support tiers. Products still define what you sell and bill. Features define what access or limit that product grants. ## How entitlements are resolved An entitlement is the resolved value of a feature for a customer. Hyperline calculates it from three possible sources: | Source | Description | | - | - | | **Default value** | The fallback value configured on the feature in the catalog. Optional. You can create features with no default. | | **Product grant** | A value granted by a product included in the customer's eligible subscription. | | **Customer override** | A value set directly on the customer. Overrides product grants and the default value. | Customer overrides always take priority. If no customer override exists, Hyperline uses product grants. If no product grant changes the value, Hyperline uses the default value from the feature catalog. Product grants contribute to entitlements when the subscription that includes the product is `active` or `paused`. Paused subscriptions keep product-granted access, while other subscription statuses do not contribute product grants. ### Features without a default value Specifying a default is optional. You can create a feature with **no default value** for both boolean and number types. When a feature has no default: * Customers receive no resolved entitlement unless a product grant or a customer override provides one. * No source is displayed for the feature on the customer **Features** tab until a grant or override is set. * Use this when access should be explicitly granted per product or per customer rather than assumed by default. For example, use it for a beta capability that only certain plans or customers should ever see. A **HubSpot integration** feature has a default value of disabled. The **Growth plan** product grants the feature as enabled. Customers subscribed to Growth receive the integration automatically, while a customer override can still enable or disable it for a specific customer. ## Feature value types Features can use two value types: | Type | Use for | Example | | - | - | - | | **Boolean** | Access that is enabled or disabled. | SSO, premium support, white-labeling, HubSpot integration. | | **Number** | Limits, quotas, or numeric entitlements. | Included seats, API calls, projects, storage in GB. | Boolean features do not require a resolution strategy. If a product grant enables the feature, the customer receives access unless a customer override changes the value. Number features use a resolution strategy to combine the default value and product grants. | Resolution | Behavior | Use when | | - | - | - | | **Maximum** | Uses the highest value across the default value and product grants. Customer overrides win. | Multiple products can increase a limit, but the customer should receive only the largest grant. | | **Sum** | Adds the default value and product grant values. Customer overrides win. | Multiple products should stack together, such as included seats or usage quotas. | | **Replace** | Uses a product grant value instead of the default value. Customer overrides win. | A product should define the entitlement value directly. | When a number feature has **no default value**, resolution falls back to the product grants and customer overrides only. Maximum and Sum ignore the missing default and compute across product grants alone, and Replace uses the product grant value directly. ### Unlimited number entitlements You can set a number entitlement to **Unlimited** to grant uncapped access instead of a finite limit. Turn on the **Unlimited** toggle next to the value when you set a product grant, a customer override, or a direct customer grant. Unlimited applies to the **entitlement value** only. The feature's catalog **default value** always stays a plain number (or empty). You can't set it to Unlimited. Unlimited interacts with the resolution strategy as follows: | Resolution | Behavior with Unlimited | | - | - | | **Maximum** | Unlimited always wins. A finite grant can never out-rank an Unlimited grant. | | **Sum** | If any contributing value is Unlimited, the resolved value is Unlimited. | | **Replace** | The applied product grant is used as-is, so the value is Unlimited only when that grant is Unlimited. Unlike Maximum and Sum, an Unlimited grant does not automatically win: a later finite grant replaces it. | As with any number feature, a customer override takes priority over product grants and the default value, so an Unlimited override grants uncapped access regardless of the product grants. An **API calls** feature has a default limit of `10000`. The **Enterprise plan** product grants the feature as Unlimited. Customers on Enterprise receive uncapped API calls, and a customer override can still set a specific number for a single customer. ## Create a feature 1. Go to **Catalog** > **Features**. 2. Click **New feature**. 3. Enter the feature **Name** and, if needed, an **Internal description**. 4. Enter a stable **Code**. Use an API-safe key such as `sso`, `hubspot_integration`, or `included_seats`. 5. Select the value **Type**: * **Boolean** for enabled or disabled access. * **Number** for quotas or limits. 6. For number features, select the **Resolution** strategy. 7. Optionally toggle **Default value** on and set the value. Leave the toggle off to create the feature with no default. Customers will only receive an entitlement when a product grant or override provides one. 8. Click **Save feature**. Use codes that match how your product team refers to access internally. Stable codes make reporting and integrations easier to maintain. ## Archive, recover, or delete a feature Features have a lifecycle in the catalog. Archive a feature when you no longer want it granted to new products or customers, and delete it when it is no longer needed at all. Open a feature from **Catalog** > **Features** and use the **Actions** menu: | Action | When to use it | Effect | | - | - | - | | **Archive feature** | You want to stop granting the feature going forward but keep it available for products and customers that already use it. | The feature is hidden from the default features list and cannot be selected when adding a new feature to a product or granting one to a customer. Existing product entitlements and customer overrides keep working. | | **Recover feature** | You archived a feature by mistake or want to grant it again. | The feature returns to the active list and becomes selectable again. | | **Delete feature** | The feature is no longer needed anywhere. | The feature is permanently removed. You can only delete archived features that are not assigned to any product or customer. Remove those assignments first. | You can only change the archive state through these actions. You can't edit it from the feature edit form. ### Filter features by status The **Features** list has a **Status** filter with three values: * **Active**: the default view. Shows features that are not archived. * **Archived**: shows only archived features. Use this view to find and recover a feature. * **All**: shows every feature regardless of status. ### Archived features on products and customers Archived features remain visible where they are already in use: * Product **Entitlements** panels continue to show archived features that are granted by the product, so you can still see and adjust their values. * Customer **Features** tabs continue to show archived features that contribute to the customer's resolved entitlements. You cannot add an archived feature to a new product or grant it as a new customer override. Recover it first, or add a different feature. ### Manage feature lifecycle from the API The same actions are available on the REST API. Use them from your own tooling or automation when you manage the feature catalog outside the app. | Endpoint | Purpose | | - | - | | `PUT /v1/features/{code}/archive` | Archive an active feature. | | `PUT /v1/features/{code}/unarchive` | Recover an archived feature. | | `DELETE /v1/features/{code}` | Permanently delete an archived feature that has no product or customer assignments. | See the [Archive a feature](/api-reference/endpoints/features/archive-feature) and [Unarchive a feature](/api-reference/endpoints/features/unarchive-feature) reference for request and response details. ## Grant features from products After you create a feature, add it to the products that include that capability or limit. 1. Go to **Catalog** > **Products**. 2. Open the product that should grant the feature. 3. In **Entitlements**, click **Add feature**. 4. Select the feature from the catalog. 5. Keep the default value or open the row to set a product-specific value. If the feature has no catalog default, you must provide an explicit value for the product grant to save. For number features, turn on **Unlimited** to grant uncapped access instead of a finite value. 6. Click **Save**. When the product is included in a customer's eligible subscription, its feature grants contribute to that customer's resolved entitlements. Entitlements do not create invoice lines or change the product price. They describe access granted by products that are already billed through subscriptions, quotes, or invoices. ## Review customer entitlements Open a customer page and select the **Features** tab to see the resolved entitlements for that customer. Each row shows the feature name, resolved value, and a tag indicating where the value comes from: | Tag | Meaning | | - | - | | **Default** | The value comes from the feature catalog. | | **Product** | The value is granted by one or more of the customer's subscribed products. Hover the tag to see which subscriptions contribute. | | **Override** | A customer-specific value is applied on top of product grants and the default. | The **Features** tab is available to members with the `entitlements_update` permission on workspaces that have entitlements enabled. ## Override a customer entitlement Use customer overrides for exceptions that should apply only to one customer, such as a negotiated limit, an early access grant, or a support-approved exception. 1. Open the customer page and select the **Features** tab. 2. Find the feature in the table and open the row's action menu. 3. Click **Edit** to open the override modal. 4. Update the **Value** and, optionally, add a **Reason** to record why the override exists. For number features, turn on **Unlimited** to grant uncapped access. 5. Click **Save**. To remove an override and let Hyperline recalculate the value from product grants and the feature default, open the row's action menu and click **Reset**. ## Grant a feature to a customer You can also grant a feature directly to a customer, even if no subscribed product includes it. 1. Open the customer page and select the **Features** tab. 2. Click **Grant feature** and select a feature from the picker. 3. Set the **Value** and, optionally, a **Reason**. For number features, turn on **Unlimited** to grant uncapped access. 4. Click **Grant feature**. The granted feature appears in the table with the **Override** tag and behaves like any other customer override. Customer overrides are customer-specific exceptions. Use them when the customer should intentionally differ from the product configuration. ## Next steps * Create billable catalog items in [Products and prices](../products/overview). * Add products to customers when you [create a subscription](../subscriptions/create). * Use [customer segments](../customers/segments) to group customers with similar access or commercial rules. # Configure your account Source: https://docs.hyperline.co/docs/getting-started/configure-account Configure your Hyperline account: business information, brand identity, logo, favicon, payment providers, and billing settings during onboarding. ## Business ### Information Fill in your company's **trade name** (the name used to conduct your business). Hyperline displays it on public pages and transactional emails. ### Brand identity Personalize the billing experience for your customers by adding your brand assets. 1. Add the **logo** you want to display on public pages, emails and documents (invoices, credit notes, quotes). 2. Add the **favicon** you will be using on public pages. 3. Select your **main brand color** by adding its HEX code. Hyperline displays it as an accent color on documents and emails. A real-time preview shows how your changes affect invoice design. ### Billing information Hyperline displays the billing information on documents (invoices, credit notes, quotes). It contains: 1. The company's **legal name**, which can be different from the trade name. 2. The company's **billing address**, including all details required by your country's laws. 3. Your company's **tax ID** (validated for EU-based companies). You cannot change the company's country as it determines your accounting currency. ## Payment methods Configure how you collect payments for each invoicing entity from **Settings > Payment**. The methods available to you depend on the entity's country and the payment providers you connect. From this page, you can: * Connect a payment provider for automated payment methods such as cards and direct debit. * Enable the payment methods you want to offer. * Select the default payment provider or bank account for each method. You can then control which of the enabled methods are available to each customer. See [Payment methods](../payments/payment-methods) for supported methods and customer-level configuration, and [Payment orchestration](../payments/orchestration) for payment provider setup. ### Bank accounts and bank transfers To let customers pay by manual bank transfer, enable bank transfers and configure the bank account that should receive the funds. Make sure its details are complete before issuing invoices: Hyperline uses the configured account to provide customers with the information they need to make the transfer. Manual bank transfers are not charged automatically. After receiving a transfer, you must reconcile it with the corresponding invoice. See [Invoice reconciliation](../invoices/reconciliations) for the available reconciliation options. ## Next steps * [Configure invoicing entities](../account/invoicing-entities) * [Review account settings](../account/settings) * [Set up sandbox and test mode](./sandbox) * [Create products and prices](../products/overview) # Quick start Source: https://docs.hyperline.co/docs/getting-started/quick-start Follow the shortest path to configure your Hyperline account, test safely in sandbox, create your first billing objects, and issue your first invoice. Use this guide when you are setting up Hyperline for the first time and want a clear path from an empty account to your first billing workflow. ## Setup path 1. [Configure your account](./configure-account) with your business information, brand assets, billing details, and default account settings. 2. [Configure your invoicing entities](../account/invoicing-entities), then review [account settings](../account/settings) for currencies, email settings, saved views, and formatting options. 3. Set up payment collection in the **Payments** section: * [Payment orchestration](../payments/orchestration) * [Payment methods](../payments/payment-methods) 4. Use [Sandbox and test mode](./sandbox) to test products, subscriptions, invoices, payments, and usage data without affecting production. 5. Create your catalog: * [Products and prices](../products/overview) * [Price books](../price-books/overview) 6. Create or import customers from [Customers](../customers/overview). 7. Create your first recurring billing flow with [Subscriptions](../subscriptions/overview), or prepare a commercial proposal with [Quotes](../quotes/overview). 8. Review generated invoices from [Invoices](../invoices/overview), then configure payment collection and reconciliation from [Payments](../payments/orchestration). ## Recommended first checks * Your business and billing details are correct. * Your invoicing entity settings match the legal entity issuing invoices. * Your account has at least one payment collection path, such as a connected provider, bank transfer details, or an outside-of-Hyperline process. * Your team members have the right permissions before they create customer, subscription, invoice, or settings changes. * You have tested your sandbox flow before production billing starts. Keep the first setup narrow. Start with one product, one customer, and one subscription or quote. Once the first flow works end to end, add more pricing, payment, and automation rules. ## Related * [Configure your account](./configure-account) * [Invoicing entities](../account/invoicing-entities) * [Account settings](../account/settings) * [Sandbox and test mode](./sandbox) * [Payment methods](../payments/payment-methods) # Sandbox and test mode Source: https://docs.hyperline.co/docs/getting-started/sandbox Use Hyperline's sandbox and test mode to safely experiment with subscriptions, invoices, and payment flows before switching to production. ## Hyperline test mode Setting up billing often requires experimentation. Use **test mode**, also called **sandbox**, to test Hyperline without affecting your production account. When you switch to test mode, Hyperline creates a separate test account. You can create test customers, subscriptions, invoices, usage events, and payments before configuring production billing. Test mode does not block outbound emails. If an action normally sends an email in production, Hyperline also sends it from your test account to the configured recipient, such as a customer email, invoice email, checkout recipient, quote recipient, or additional email recipient. Use internal or dedicated test email addresses for sandbox customers and recipients unless you intentionally want a real recipient to receive the message. Test mode has the same product capabilities as your production account. Use the product documentation to configure your [product catalog](../products/overview), manage [templates](../subscriptions/templates), [send invoices](../invoices/overview), [use credits and wallets](../wallets/balance), and more. You can also manage your team from inside sandbox. Invite members, revoke access, merge duplicate members, and transfer ownership all work the same way in sandbox as in production. See [Users & permissions](../account/users-permissions) for the steps. ## Switching between production and sandbox A single permission, **test mode read**, controls access to sandbox: * To **enter** sandbox from production, a member needs the **test mode read** permission on their role. * To **switch back** from sandbox to production, no extra permission is required. Any member already in sandbox can return to production, and access to production data is enforced server-side by their production role. Grant **test mode read** to any role whose members should be able to open sandbox from the account switcher. ## Testing payments Test payment provider and gateway flows in sandbox before connecting production bank accounts or production payment provider accounts. Sandbox payments use sandbox payment provider accounts, so no real money is charged or debited. If your sandbox account was populated from production data or from another billing system, you cannot use existing production payment methods in sandbox. Production cards, mandates, and bank authorizations are not compatible with sandbox payment provider accounts. ### Add a test payment method To test automatic payments, add a test payment method to the sandbox customer from a hosted page: 1. Open a sandbox hosted page for the customer, such as a quote signature page, checkout page, invoice page, or customer portal. 2. Go to the **Add payment method** section. 3. Enter test payment details from your payment provider. Use the provider's test credentials: * [Stripe test cards](https://docs.stripe.com/testing#cards) * [Stripe SEPA Direct Debit test details](https://docs.stripe.com/testing?payment-method=sepa-direct-debit#non-card-payments) * [Adyen test cards](https://docs.adyen.com/development-resources/test-cards-and-credentials/test-card-numbers) * [Adyen SEPA Direct Debit test details](https://docs.adyen.com/payment-methods/sepa-direct-debit/web-drop-in#test-and-go-live) * [Adyen ACH Direct Debit test details](https://docs.adyen.com/payment-methods/ach-direct-debit/web-drop-in#test-and-go-live) * [Adyen Bacs Direct Debit test details](https://docs.adyen.com/payment-methods/bacs/web-drop-in#test-and-go-live) * [Mollie test cards](https://docs.mollie.com/overview/testing#testing-different-types-of-cards) Once you add a test payment method, Hyperline can charge future invoices automatically with it. To test payment collection on an existing invoice, open the invoice and click **Actions** > **Charge invoice**. ## Simulate usage data without code This applies if you want to **configure your first usage-based plan** and **assign a subscription to a customer** in order to test Hyperline. In the test account, you can simulate usage data by generating fake events for a specific customer. This takes two steps: Then click the **Events** tab, and click **Simulate new events**. Fill in: * **The event type**: the event name used to aggregate usage in your billing plan configuration (API calls, email sent, document retrieved or created, etc.) * **The date** (leave blank if you prefer) * **The number of events to create** * You can optionally add extra parameters to your event with the **JSON Payload field.** Click **Create new events** when you are ready. The events can take a few seconds to be ingested. They will appear in your customer's **Events page**. You can easily delete them in the **Events page** afterward. You are done. You can now create your first usage-based plan based on these events. ## Multiple accounts If you belong to several Hyperline accounts, use the account switcher to move between them without signing out. Each account has its own settings, members, permissions, customers, catalog, billing data, and integrations. You can therefore use separate accounts for different companies or legal entities that require fully independent configurations. You manage members and roles separately for each account. See [Users & permissions](../account/users-permissions) for details. # Documentation Source: https://docs.hyperline.co/docs/index Hyperline documentation: manage customer intelligence, CPQ, subscriptions, AI monetization, invoicing, payments, accounting, and developer integrations.
Decorative background image Decorative background image
# Documentation
Hyperline helps B2B software companies manage complex revenue workflows, from customer intelligence and CPQ to subscriptions, AI monetization, invoicing, payments, accounting, and developer integrations.
Manage customers, segments, usage, health signals, and customer intelligence workflows. Create quotes, structure contracts, manage subscriptions, and support hybrid pricing. Track usage, sell prepaid credits, manage balances, and apply these patterns to AI monetization. Generate invoices, manage taxes, documents, reminders, e-invoicing, and exports. Connect payment providers, collect payments, retry failures, and reconcile transactions. Track revenue, manage ledgers, automate journal entries, and handle revenue recognition.
# Glossary Source: https://docs.hyperline.co/docs/introduction/glossary Look up Hyperline billing terminology, including customers, products, subscriptions, invoices, aggregators, and ledgers, with clear definitions. Is something still unclear? Don't hesitate to [reach out to our team](mailto:support@hyperline.co) if you need additional support. ## Core entities | Term | Definition | | - | - | | **Bundle product** | A product that groups several existing products as components and sells them as a single unit. Distinct from the "bundle" pricing model. | | **Customer** | An individual or company that purchases your products/services. Has billing information, payment methods, and can have multiple subscriptions. | | **Invoice** | A document requesting payment from a customer. | | **Product** | A billable item in your catalog. | | **Quote** | A sales proposal sent to customers before creating a subscription. Can be signed electronically or manually. | | **Subscription** | A recurring billing agreement between you and a customer, defining which products are included, pricing, and billing schedule. | ## Subscription | Term | Definition | | - | - | | **Activation strategy** | How a subscription becomes active. | | **Cancellation** | Ending a subscription. | | **Contract terms** | Terms governing the subscription contract including start/end dates, duration, and renewal settings. | | **Proration** | Calculating partial charges when changes occur mid-billing period. | | **Renewal** | When a subscription automatically continues for another term. | | **Subscription phase** | A distinct period within a subscription with its own products and terms (e.g., trial, standard). | | **Subscription template** | A pre-configured subscription setup that can be reused for multiple customers or contexts (currency/country combinations). | | **Subscription update** | A pending change to a subscription (add/remove products, change prices, apply coupons). | | **Trial period** | A free or discounted phase before regular billing begins. | ## Pricing and billing | Term | Definition | | - | - | | **Billing interval** | How often a customer is charged (e.g., monthly, yearly, weekly). | | **Commitment period** | Minimum contract duration for a subscription (e.g., 1-year commitment). | | **Price book** | A collection of custom price configurations that can be assigned to specific customers for special pricing. | | **Price configuration** | Defines how a product is priced. Includes currency, billing interval, and pricing model. | | **Pricing model - BPS (Basis Points)** | Percentage-based pricing typically used for payment processing fees. | | **Pricing model - Bulk** | A single price per unit is applied based on the total usage tier (e.g., 150 units all priced at the 101-200 tier rate). | | **Pricing model - Bundle** | Predefined quantity/price packages on a seat or credit product (e.g., 1000 credits for $50, or 10 seats for $180). Distinct from a Bundle product, which is a product type. | | **Pricing model - Fee** | A fixed amount charged per billing period (e.g., \$99/month). | | **Pricing model - Packaged** | Units are sold in packages/bundles (e.g., \$100 per 1000 API calls). | | **Pricing model - Volume** | Price per unit decreases as usage increases through tiers (e.g., first 100 units at $0.10, next 100 units at $0.08). | ## Usage and metering | Term | Definition | | - | - | | **Billable event** | A usage record sent via API that represents a customer action to be metered (e.g., API call, message sent, storage used). | | **Committed count** | A guaranteed minimum usage amount that will be charged regardless of actual usage. | | **Metering configuration** | Defines how billable events are counted or summed for billing. | | **Metering filter** | Conditions applied to narrow down which events count toward billing (e.g., only count events where `region = 'us'`). | | **Usage interval** | The period over which usage is measured before billing (can differ from billing interval). | ## Credits and wallet | Term | Definition | | - | - | | **Credit transaction** | A record of credits being added, consumed, or expired. | | **Credits** | Pre-purchased units that can be consumed against usage-based products. Can expire. | | **Low balance threshold** | A configurable threshold that triggers notifications when credits or wallet balance falls below. | | **Top-up** | Adding credits or wallet balance to a customer's account. | | **Wallet** | Funds intentionally held as a reusable customer balance that can pay future invoices automatically or manually. | | **Wallet transaction** | A record of funds being credited to or consumed from a customer's wallet. | ## Discounts and promotions | Term | Definition | | - | - | | **Coupon** | A discount that can be applied to subscriptions. Can be a fixed amount or percentage off. | | **Coupon duration** | How long a coupon applies. | | **Coupon repeat** | Controls coupon application frequency. | | **Promotion code** | A shareable code that customers can use to redeem a coupon. Can have usage limits and expiration. | ## Documents | Term | Definition | | - | - | | **Checkout page** | A hosted payment page where customers can enter payment details and complete a purchase. | | **Checkout session** | A hosted page experience for customers to complete payment and subscription activation. | | **Contract clause** | Reusable text blocks that can be included in contracts. | | **Contract template** | Legal document templates that can be attached to quotes. | | **Credit note** | A document issued to reverse or reduce a previously issued invoice. | | **Customer portal** | A self-service interface where customers can view invoices, manage subscriptions, and update payment methods. | | **Invoice line item** | An individual charge on an invoice representing a product or adjustment. | | **Purchase order** | A customer's reference number for their internal tracking. | | **Quote template** | Reusable configuration for quotes including terms, display options, and attached documents. | ## Approvals | Term | Definition | | - | - | | **Approval request** | A request created when a quote, invoice finalization, or credit note finalization matches an approval workflow. Tracks the approval status and history. | | **Approval step** | A stage in an approval workflow where designated approvers must approve or reject before proceeding. | | **Approval workflow** | A configurable set of rules and steps that determines when and how quotes, invoices, or credit notes require approval. | | **Approver requirement** | Whether any single approver or all designated approvers must approve a step (`any` or `all`). | | **Workflow condition** | A rule that determines if a workflow applies to an action, for example when the total amount is greater than €10,000. | | **Workflow priority** | A number used to select between multiple matching workflows. Higher priority workflows are selected first. | ## Payments | Term | Definition | | - | - | | **Allocation** | The amount of a transaction or credit note currently applied to a specific invoice or credit note. | | **Bank account** | Customer's bank account details used for manual bank transfer payments. | | **Chargeback** | When a customer disputes a charge with their bank, resulting in reversed payment. | | **Dunning** | The process of automatically retrying failed payments and communicating with customers to collect overdue invoices. | | **Grace period** | A delay between invoice creation and payment collection, allowing review or manual adjustment. | | **Payment method** | How a customer pays (card, direct debit, bank transfer, etc.). | | **Payment method state** | Current status of a payment method. | | **Payment service provider (PSP)** | A third-party service that processes payments (e.g., Stripe, GoCardless, Mollie). | | **Transaction** | A recorded money movement, such as a payment, refund, or chargeback. It does not by itself represent wallet balance. | | **Unallocated amount** | The part of a transaction not yet assigned to a document or wallet and waiting for a matching decision. | ## Organization | Term | Definition | | - | - | | **Client** | Your account/organization in Hyperline (the seller). | | **Custom field** | User-defined properties that can be added to customers, subscriptions, products, plans, or quotes. | | **Invoicing entity** | A legal entity that issues invoices (your company or subsidiaries). Has its own branding, address, tax ID, and numbering sequences. | | **Local tax number** | A country-specific customer tax identifier used for local invoicing or reporting requirements. It is separate from the primary Tax ID and is not validated through VIES. | | **Tax ID** | A tax identification number (e.g., VAT number) for a customer or invoicing entity, used for tax compliance and validation. | | **Tax rate** | VAT/sales tax rates applied to invoices. | | **Tax scheme** | How tax is applied to an invoice. | ## Analytics and reporting | Term | Definition | | - | - | | **ARPA (Average Revenue Per Account)** | ARR divided by the number of active customers. | | **ARR (Annual Recurring Revenue)** | The recurring revenue normalized to a yearly amount, based on the subscription's currently active phase. Future phases are reflected when they become active. | | **Churn** | When customers cancel their subscriptions or reduce spending. | | **Contract value** | Total value of a subscription over its full contract term. | | **Estimated ARR** | Projected annual revenue from a subscription including variable/usage components. | | **MRR (Monthly Recurring Revenue)** | The value of recurring revenue normalized to a monthly amount. | | **TCV (Total Contract Value)** | The total value of all committed phases across the full contract term. Unlike ARR, it includes future phases before they become active. | A subscription has an active phase at $150 per month, followed by a later committed phase that brings the total contract value to $3,290. While the first phase is active, ARR is $1,800 ($150 x 12). TCV is \$3,290 because it includes the full committed contract. ## Integrations | Term | Definition | | - | - | | **External ID** | Your system's identifier for a customer, used for mapping records. | # Why building billing in-house is risky Source: https://docs.hyperline.co/docs/introduction/why-billing-is-complex Understand why building a billing system in-house is risky for growing software companies, and how a dedicated platform supports pricing changes. Is your company growing? Congratulations! It is now time to charge your first customers. But how? Let's be frank: billing may not be the most glamorous aspect of your business, but it is a pivotal factor that can define your success. From day one, successful software companies have known how crucial it is for their billing solution to match their pricing strategy perfectly. For instance, Zoom swiftly adopted usage-based billing to accommodate a 30x surge in demand during the pandemic. If you're a founder, finance operator, or engineering leader, you're likely wondering whether it's best to build your billing system in-house or opt for a ready-made solution. Today, we're diving into the **'Build vs. Buy' dilemma**. Initially, as you embark on this journey, billing might seem straightforward. Your pricing structure is simple, making subscription management look easy. This also allows you to protect your profit margins by avoiding third-party billing services like Stripe Billing or Chargebee, which take a share of your earnings. However, as your business scales, you'll discover that billing is more complex than initially anticipated. Still wondering if building your own billing system is a good idea? Let's talk about it. We are here to answer all your questions. ## Subscription and usage-based models Launching a billing system typically begins with subscription-based billing. In this approach, you assign each customer to a specific plan to ensure accurate charges at the right interval. **The fact is that complex pricing models are at the core of modern business operations**. As your company grows, you will likely implement various pricing strategies to optimize revenue and cater to client needs. This growth may entail the adoption of usage-based pricing, transactions, credits, custom subscriptions, coupons, or a mix of these items. Managing a large number of subscriptions is already challenging, and dealing with complex subscriptions adds another layer of billing complexity. For instance, adopting usage-based billing will require advanced metering and tracking systems. ## Taxation complexity As your business expands globally, dealing with taxes becomes a major factor that increases billing complexity. Several factors influence taxes: what you're selling, your location, and where your customers are. Each location has its own tax regulations, so it's crucial to comply with them everywhere you do business. For instance, consider a European company trying to figure out how to apply VAT (courtesy of Chargebee). It's a complex process with many possibilities. Ensuring the correct tax rate is applied based on where you and your customer are located is challenging if done manually. Maintaining these tax rules over time can be especially tough if you're building your own in-house billing system. ## Payment intervals management The challenge of billing complexity becomes particularly evident when you delve into date management. Imagine a scenario in which a company offers: * a platform access fee charged annually * a metered product charged every month * an onboarding fee charged once * a 3-month free trial for each pricing plan, etc. *Does it sound familiar?* This scenario demands the management of various payment intervals, alongside the coexistence of free and paid options, resulting in the need for intricate date management. Coordinating the timing of customer transitions from free to paid services, all while managing the billing cycles, due dates, and renewals for these different models, requires meticulous attention to detail. Considering these complexities, it becomes obvious that you need a solution that can effectively handle all of these challenges for you. ## Custom pricing Companies of all sizes often need to go beyond standard pricing. Custom pricing is vital in particular situations, allowing them to adjust their pricing plans to match the unique needs of each customer. This goes from special contracts for Enterprise deals to tailored packages for specific needs. However, managing these custom pricing arrangements with an in-house billing system can be challenging in the long run. This is where a flexible billing system becomes crucial. It should adapt to the diverse pricing needs of each client or situation, making it easier to manage custom pricing, maintain good customer relationships, and increase revenue over time. ## Multi-currency transactions Operating in a global market means dealing with multiple currencies. Converting and reconciling transactions in different currencies requires meticulous attention to detail. When you're building your own billing solution, it's very hard to follow up manually. For instance, consider a software company based in the U.S. that sells licenses to customers in Europe. The billing system must convert the sale amount from euros to dollars, accounting for any fluctuations in the exchange rate. On that same subject, it's also imperative to have aggregated metrics that take into account operations in various countries and currencies. These metrics give you a comprehensive understanding of the financial health of your business. These aggregated metrics, such as ARR (Annual Recurring Revenue) on a global dashboard, provide a holistic view of the company's performance. This not only ensures accurate financial reporting but also supports the generation of globally aggregated metrics that help in strategic decision-making. These dashboards may well be built in-house, but they're hard to keep afloat over time when your billing system is evolving and has been built from scratch. ## The challenge of dunning Dunning is the process of dealing with payments that didn't go through from customers. It makes billing more complicated for a couple of reasons: * **Automatic retries without manual intervention**: When a payment fails, you need to give it another shot without needing to remember to do so yourself. Having an automated system that can detect these payment issues and try again is crucial; otherwise, it can become a real headache. * **Effective customer communication**: When a customer's payment fails, you have to let them know in the right way. It's a delicate balance between informing them about the problem and ensuring they still have a positive experience. That's why having an emailing system built into your billing process is helpful; trying to manage it manually can be quite challenging. * **Entitlements for service access**: Additionally, there's a need for app logic that handles entitlements, which determine access to the service. Managing these entitlements to restrict access when payments fail adds another layer of complexity to the dunning process. ## Conclusion The path to billing success often leads to the realization that building an in-house billing system might not be the most practical choice. Instead, opting for a flexible billing solution can offer the adaptability and efficiency needed to navigate these complexities. By choosing the right tools, you can streamline your billing processes, maintain strong customer relationships, and continue on the path to growth and success. Want to learn more about this topic? [Read our blog article](https://www.hyperline.co/resources/blog/billing-simplified). # Invoice approvals Source: https://docs.hyperline.co/docs/invoices/approval Submit draft invoices and credit notes for internal approval before finalization, review requests, and handle requested changes. Invoice and credit note approvals let your team review draft billing documents before they are finalized. Start with [Approval workflows](/docs/account/approvals) to configure shared rules, approval steps, priority, notifications, and delegations. This page covers when invoice approvals apply and how to submit and review documents. ## Configure invoice and credit note approvals Follow the [workflow setup steps](/docs/account/approvals#configure-approval-workflows) and select **Invoice finalization**, **Credit note finalization**, or both under **Applicable flows**. Use the [shared conditions](/docs/account/approvals#rules) to decide which documents require review, then select the team members or roles responsible for each approval step. Require a finance manager to approve invoices and credit notes with a total amount above \$50,000. Select both finalization flows and add a finance review step so the same rule applies to both document types. ### When approval applies These workflows apply when someone manually submits a draft invoice or credit note for finalization in Hyperline. They also apply when a draft document is submitted through an integration using the API. If no workflow matches, Hyperline finalizes the document immediately. An approval workflow does not make invoices or credit notes draft by itself. To review invoices generated from subscriptions, configure draft invoice behavior separately using **Generate draft invoices** in the [subscription invoicing settings](/docs/subscriptions/update#invoicing), or enable [**Force draft invoices**](/docs/customers/overview#force-draft-invoices) for the customer. ## Approval process ### For invoice and credit note creators 1. Prepare your [draft invoice](/docs/invoices/manage#create-draft) or [credit note](/docs/invoices/refunds). 2. Submit the draft for finalization. If it matches a workflow, it moves to `pending_approval` and remains unfinalized. 3. Open the document to see the workflow that was triggered, the current step, and the approval history. 4. After the final approval step, Hyperline finalizes the document automatically. If an approver rejects the request, Hyperline notifies you and moves the document to `changes_requested`. Edit and save it to submit a new approval request, or delete it if you no longer need it. ### For approvers 1. Open the invoice or credit note from your approval notification, or filter the **Invoices** list by **Pending approval**. 2. Review the document details and approval history. 3. Click **Approve** to move the request to the next step, or **Reject** to request changes. Enter a **Reason** for the creator when rejecting a request. After the final approval step, Hyperline finalizes the document automatically. If you reject it, Hyperline notifies the creator, who can edit and resubmit it. You can also act directly from a Slack approval notification. See [Notifications](/docs/account/approvals#notifications) for setup. ## Invoice and credit note statuses | Status | Meaning | | - | - | | `pending_approval` | The document is waiting for approval at one or more steps. It remains unfinalized. | | `changes_requested` | An approver rejected the request. Edit and save the document to resubmit it, or delete it. | After the last step is approved, Hyperline finalizes the document and moves it to its normal post-finalization status. Filter the **Invoices** list by **Pending approval** or **Changes requested** to find documents awaiting review or edits. ## Next steps * [Configure approval workflows and delegations](/docs/account/approvals). * [Create and manage invoices](/docs/invoices/manage). * [Manage credit notes](/docs/invoices/refunds). # Invoice configuration Source: https://docs.hyperline.co/docs/invoices/configuration Configure Hyperline invoices from settings: brand assets, trade and legal names, tax IDs, footers, numbering format, and default behaviors. If you did not already configure your invoices during the initial onboarding process, you can do it anytime from Hyperline's interface, from the **Settings** pages. ## Business In the **Business** section, you can customize your brand's logo and color that will appear on your invoices. You also need to fill in the trade and legal names of your company, your tax ID (if applicable), and the postal address that will appear on the invoices. These details are required to make your invoices legally compliant. Hyperline shows a real-time preview on the right of the screen so you can see how your changes affect your invoice design. Click **Save changes** once you are done. ## Invoicing You can customize settings that will apply to all generated invoices. Hyperline applies new configurations to invoices generated after you save the changes. #### Invoicing number You can customize how Hyperline numbers your invoices. You can do this in **Settings**, in the **Invoicing** section. Each invoice must have a **unique number**. These numbers should follow a sequential order. This is a legal requirement that applies internationally. However, Hyperline lets you select the invoice number pattern you want to use. The `{number}` variable is mandatory. You can then add any text, the year variable `{YYYY}`, the month variable `{MM}` and/or the day variable `{DD}` to customize the invoice number format. | Variable | Invoice number format | | - | - | | number | 1 | | number-YYYY | 1-2023 | | number-YYYY-MM | 1-2023-10 | | number-YYYY-MM-DD | 1-2023-10-10 | | YYYY-MM-DD-00number | 2023-10-10-001 | #### Invoice legal information As legal requirements vary from country to country, and are sometimes industry-specific, Hyperline provides a space for you to add any relevant legal information to your invoices. Check in with your legal and accounting teams if needed to make sure you include all necessary information here. It can go from tax specificities to penalties applied if the invoice is not paid on time, to anything else. #### Additional information You can insert here any additional information you'd like to provide. It could be details about your invoicing policy (late payment fees, conditions, etc.) or mentions about taxes if relevant. By clicking the globe icon on the right side of the text area, you can translate both the legal and additional information into multiple languages. Hyperline automatically selects the relevant language when it generates the invoice. #### Template variables Invoice-family text fields support template variables that Hyperline replaces with the corresponding value when it generates the document. Supported fields include: * Invoice footer, additional information, and late fees * Credit note footer and additional information * Custom document footer and additional information * Custom note on invoices and on the subscription invoicing options form | Variable | Replaced with | | - | - | | `{{customerId}}` | The customer's Hyperline ID | | `{{customerExternalId}}` | The customer's external ID | | `{{subscriptionId}}` | The subscription's ID, only rendered when the invoice is tied to a subscription, otherwise hidden | | `{{invoiceId}}` | The invoice's ID | | `{{invoiceNumber}}` | The invoice's number | | `{{quoteNumber}}` | The quote's number | For example, a footer set to `Please reference {{invoiceNumber}} and subscription {{subscriptionId}} in your payment.` produces a fully populated line on subscription-generated invoices. On standalone invoices that aren't linked to a subscription, `{{subscriptionId}}` is omitted. Quote footers and quote or contract templates don't support `{{subscriptionId}}`, because a quote isn't yet tied to a subscription. # Consolidated invoicing Source: https://docs.hyperline.co/docs/invoices/consolidated-invoicing Merge a customer's subscription invoices billed on the same day into one consolidated invoice, so they receive and pay a single invoice instead of many. Consolidated invoicing groups a customer's subscription invoices that fire on the same day into a single aggregated invoice. Each source invoice is held until Hyperline merges them into one consolidated invoice, which is then finalized, numbered and charged as usual. Use this when a customer has several subscriptions billing on the same day, for example multiple product lines or seats renewing together. You can then send them one invoice instead of several. ## How it works * Consolidation is a per-customer setting (`Consolidate invoices` toggle on the customer). * Hyperline groups each eligible invoice by the day it was scheduled to bill, in the customer's timezone. * Once the day has fully elapsed, Hyperline merges every held invoice for that day into a single new invoice (the **aggregate**) and marks the source invoices as **Consolidated**. * The aggregate is what gets finalized, numbered and charged. Source invoices never receive a number of their own. ### What's eligible Only invoices that meet all of these are held for consolidation: * The customer has `Consolidate invoices` enabled. * The invoice comes from a subscription (one-off invoices, documents and credit notes are excluded). * The invoice is not from an external source (imported invoices go through their own flow). * The invoice is of type `invoice` (credit notes and other document types are excluded). Ineligible invoices follow the normal lifecycle unchanged. ### Grouping by day Hyperline groups invoices by their **billing date** in the customer's timezone: * Bill-in-advance invoices group on the period start. * Bill-in-arrears invoices group on the period end. * Backdated subscriptions (a subscription created after its start date) group on the day they *would have* billed, not the day the catch-up invoice was actually emitted. This means a subscription starting July 1 but created on July 10 lands in the July 1 group, not July 10. ### The merge Hyperline waits until: 1. The consolidation day has fully elapsed in the customer's timezone, and 2. There are no pending renewals or in-flight invoices for that day still to land. Once both conditions are met, Hyperline merges all held invoices for the day into a single aggregate invoice: * Every line item from every source invoice is copied over, prefixed with the source subscription name so you can trace what came from where. * Line-item amounts, tax rate, tax amount, discounts, proration and debit/credit sign are preserved verbatim. The aggregate total equals the sum of the source invoices. * The aggregate carries no `subscriptionId` of its own (it spans several), so it is never itself held for consolidation. If only one invoice was held for the day, Hyperline doesn't create an aggregate. It releases and finalizes the lone invoice directly, so it never gets stuck waiting. ## Enable consolidated invoicing for a customer The toggle lives on the customer page, in the **Advanced** section of the customer edit form. Go to **Customers** and select the customer. Open the customer edit form and scroll to the **Advanced** section. Enable the toggle labelled **Consolidate invoices**. From this point on, Hyperline holds new subscription invoices for this customer until the daily merge. The customer panel shows the current state as a tag (**Enabled** / **Disabled**) next to the `Consolidate invoices` label, alongside the other invoicing settings. You can turn consolidated invoicing off at any time. However, if the customer has invoices currently held (`Pending consolidation`), you'll need to let those merge (or delete them) before the toggle takes effect on new invoices. ## Invoice statuses Consolidated invoicing introduces two invoice statuses in addition to the [standard ones](./overview#invoice-status): `Pending consolidation` The invoice is held, waiting for the daily merge. It has no invoice number yet and hasn't been charged. Only action available: **delete** (see below). `Consolidated` The invoice was merged into an aggregate. It links to the aggregate invoice via `linkedInvoiceId`. The source is kept for record-keeping but the aggregate is what's charged. Both statuses appear in the invoice list and on the invoice detail page. ## The invoice detail page Hyperline surfaces the consolidation relationship directly on the invoice page: * **On a `Consolidated` source invoice**: a callout at the top of the page links to the aggregate the invoice was merged into. * **On an aggregate invoice**: a callout at the top of the page shows the number of source invoices consolidated into it. It also links to the filtered list of those sources. ## Actions on held invoices A `Pending consolidation` invoice is an internal, un-numbered state. It isn't a document to send. The available actions are limited on purpose: * **Delete** is allowed, so you can drop an invoice out of the day's group before it merges (for example, if the underlying subscription change was wrong). ## Stuck consolidations A group won't merge until the day is complete. Hyperline waits on: * Any subscription renewal for that day that hasn't fired yet. * Any peer invoice for the same day still in `grace_period`, `draft` or otherwise in-flight. ## Consolidated invoicing and organisation-based billing Consolidated invoicing composes with [organisation-based billing](../customers/organisation-based): * If the customer is an org **child**, the aggregate is routed to the parent following the child's org invoicing configuration (`Individual invoices` → `Charged on parent`, `Grouped` → `Pending parent concat`). The parent collects payment as usual. * If only a single invoice ends up being held for the day, that lone invoice is routed to the parent directly rather than being finalized standalone. ### Consolidating child invoices on the parent You can also consolidate the invoices of several children on the parent. A parent with multiple children, each running their own subscriptions, then receives a single consolidated invoice per day instead of one per child subscription. To set this up: 1. On each child, open **Actions** > **Parent settings** and set the invoicing configuration to `Individual invoices`. **Do not enable `Consolidate invoices` on the children.** 2. On the parent, enable `Consolidate invoices`. With this configuration, each child subscription emits an un-numbered invoice in `Pending consolidation` state directly on the parent. At the end of the day, Hyperline merges all of these invoices into a single consolidated invoice on the parent. Hyperline then finalizes, numbers and charges this invoice as usual. ## Notes and limitations * Consolidation happens at most once per customer per calendar day (in the customer's timezone). Two subscriptions billing on the same day are merged; two subscriptions billing a day apart are not. * Held invoices don't get an invoice number. Hyperline assigns the number to the aggregate when it's finalized. Your invoice number sequence is unaffected by consolidation (only the aggregate consumes a number). * Credit notes are never held for consolidation and follow the normal flow. * Tax is copied per-line from the source invoices rather than re-resolved by the tax engine, so the aggregate total is guaranteed to equal the sum of the sources. # Custom documents Source: https://docs.hyperline.co/docs/invoices/documents Create custom Hyperline documents with unique names that behave like invoices: numbered, payable, and tailored to specific business needs. In Hyperline, you can create custom documents with unique names that function like invoices: numbered, payable, and tailored to your specific business needs. These documents can serve various purposes, such as providing informational materials for customers or issuing special payment receipts required by clients outside the standard invoicing process. Hyperline generates a document when you check the **Generate documents instead of invoices** option while creating a subscription. Hyperline then sends this document to the customer instead of an invoice. See more on the [subscription creation page](../subscriptions/create). ## Configuring your documents You can customize your documents by going to the **Settings > Invoicing** section. You have access to: * The **document number pattern**. * The available variables are: `number`, `YYYY`, `MM`, `DD`. * `number` is mandatory. * The **next document number**. This is a read-only field that shows the next document number that will be generated. If you want to update the value, please contact our support team. * The **document legal information**. This field is optional. * The **additional document footer**. This field is also optional. Hyperline displays this information on all the documents it generates. By clicking the globe icon on the right of the text area, you can translate the additional and legal information into multiple languages. Hyperline automatically selects the relevant language when it generates the document. If no relevant translation exists, Hyperline uses the default value. # Chorus Pro Source: https://docs.hyperline.co/docs/invoices/einvoicing/chorus-pro Send invoices automatically to French public administrations via Chorus Pro with Hyperline's e-invoicing integration for B2G and G2G sales. ## What is Chorus Pro Chorus Pro is the official digital portal managed by the French public sector (AIFE), used to manage electronic invoicing with government entities in France. As of today, it allows automatic transmission of invoices to public administrations (G2G/B2G sales). Since early 2020, all companies operating in France, regardless of their size, are required to submit invoices to public bodies (ministries, local authorities, hospitals, etc.) via Chorus Pro. With the upcoming French e-invoicing reforms (2026-2027), Chorus Pro will become part of a broader "Portail public de facturation" (PPF), handling e-invoices between companies and public administrations. ## Setup Before setting up the integration, you need to configure a "Raccordement" (EDI/API). From the [Chorus Pro portal](https://portail.chorus-pro.gouv.fr), connect to your account. * Go to **Domaines** > **Raccordements** in the main menu * Go to the **Technical Account** section (**Compte technique** in French) * Set the type of request to **Création d'un compte technique** in French * Select your company in the company field * This creates a login and password. **Copy these credentials**, as you'll need them when setting up Chorus Pro in Hyperline. * Ensure you have entered your **VAT number** and **Registration number** (SIRET in France) on your invoicing entity. * In **Settings > Invoicing**: * Enable **Chorus Pro**. This option is only available for French invoicing entities. * Click the **Add credentials** button and enter your technical account credentials in the Supplier portal that opens. Once logged in, you can safely close the portal. ### Testing To test in sandbox mode, create an account in the [Chorus Pro sandbox](https://qualif.chorus-pro.gouv.fr/). Download the CSV file with test accounts and use one of them to log in. For more information, visit the [Chorus Pro documentation](https://portail.chorus-pro.gouv.fr/aife_documentation?sys_kb_id=2f95a09d3bbaae102e11034a85e45a6d\&id=kb_article_view). ## Enable Chorus Pro on customers Chorus Pro automatic transmission is only relevant for government-affiliated customers (B2G sales). For Hyperline to send invoices via Chorus Pro, you need to enable the **Government affiliated** flag on the relevant customers. For each customer where Chorus Pro transmission applies, go to the customer details page, click **Edit** in the **Information** section, and toggle on the **Government affiliated** option. ## Routing By default, Hyperline routes invoices to the customer using their registration number (SIRET), which identifies the public institution. On the customer details page, click the **Edit** button in the **Information** section and set the value in the **Registration number** field. Hyperline does not automatically transmit invoices via Chorus Pro for customers with a missing registration number. Both your invoicing entity and your customer must have a **14-character** SIRET for Chorus Pro to accept the invoice. ### Service code For some public institutions, an additional service code is required to route the invoice. This code identifies the service within the public institution. If not provided, the invoice may be rejected during transmission. To add service-specific routing for a customer, open the customer details page, click **Edit** in the **Information** section, then complete the **Service code** field. Leave this optional field empty when the customer's SIRET is sufficient. The e-invoicing code field on the customer form is labelled dynamically. For a government-affiliated customer whose invoicing entity has Chorus Pro enabled, the field appears as **Service code**, even when France PA is also enabled on the same invoicing entity. # French e-invoicing with a PA Source: https://docs.hyperline.co/docs/invoices/einvoicing/france-pa Transmit French domestic B2B e-invoices in Factur-X format through a Plateforme Agréée using Hyperline or Pennylane, with customer routing setup. A **Plateforme Agréée (PA)** transmits electronic invoices between French companies and reports the required invoice data to the French administration. Hyperline supports PA transmission for domestic B2B invoices in Factur-X format. ## How invoice exchange works For both receiving and sending e-invoices, each French business must choose a PA. The PA is the authorized connection to the **Portail Public de Facturation (PPF)** and to the other PAs. The PPF is the public infrastructure operated by the French administration. You do not select it as a provider in Hyperline. The PPF maintains the central directory that identifies each business's chosen PA and its invoice-routing address. It also collects and processes the invoice, transaction, and payment data sent by PAs to the administration. When you issue an eligible domestic B2B invoice from Hyperline, the exchange follows this flow: 1. Hyperline sends the invoice to the PA you selected for issuing invoices. 2. The issuing PA uses the PPF directory to identify the customer's PA and routing address. 3. The issuing PA sends the invoice to the customer's PA. 4. The customer's PA delivers the invoice to the customer's accounting system or invoice portal, such as Coupa, SAP Ariba, or Esker. 5. The PA sends the required invoice, transaction, and payment data to the administration through the PPF. Hyperline does not connect directly to each customer's invoice portal. The PA network and the PPF directory provide the standard route to the customer's chosen receiving solution. For an invoice issued in Hyperline, the path is: Hyperline → issuing PA → PPF directory → customer's PA → customer's ERP or invoice portal. ## What Hyperline handles All businesses established in France must be able to receive e-invoices from September 2026. Receiving invoices requires a PA, but Hyperline does not handle invoice reception. Hyperline supports the issuing flow for domestic B2B invoices. To send these invoices, select either Hyperline, using Invopop's PA, or Pennylane when you use Pennylane as your PA. For invoices to French public administrations, use [Chorus Pro](./chorus-pro) instead. ## Reform timeline France is introducing its e-invoicing requirements in two phases. All companies established in France must be able to receive electronic invoices from the first phase, while the obligation to issue them depends on company size. | Phase | Date | Requirement | Companies concerned | | - | - | - | - | | **Phase 1** | September 1, 2026 | Receive e-invoices | All companies established in France | | **Phase 1** | September 1, 2026 | Issue e-invoices and submit e-reporting | Large companies and mid-sized companies (ETI) | | **Phase 2** | September 1, 2027 | Issue e-invoices and submit e-reporting | Small and medium enterprises (SMEs) and micro-businesses | If your company generates less than €50M in annual revenue, the issuing and e-reporting requirements apply from September 2027. You must still be able to receive e-invoices from September 2026. ## Choose your PA connection You can transmit French e-invoices from Hyperline using one of two connections. Both options are available to all accounts and appear with a **BETA** tag in the invoicing entity settings. ### Hyperline Select **Hyperline** to send domestic B2B invoices through Hyperline's connection, powered by Invopop's accredited platform. Your invoicing entity must be registered before invoices can be exchanged. You can follow the registration status from **Settings > Invoicing**. ### Pennylane Select **Pennylane** if your company uses Pennylane as its PA. Your invoicing entity must be connected to Pennylane in Hyperline, and Pennylane must be registered as the PA for your company. The Pennylane option stays disabled until the Pennylane connection is ready. If Pennylane is disconnected or does not have the required permissions, reconnect it before selecting this option. ## Configure France PA 1. Go to **Settings > Invoicing**. 2. Select the relevant French invoicing entity. 3. In **French e-invoicing**, select **Hyperline** or **Pennylane** for business e-invoicing (B2B). 4. Complete the registration or reconnection requested for the selected provider. 5. Click **Save changes**. Once the connection is ready, Hyperline automatically transmits eligible domestic B2B invoices through the selected PA and displays their transmission status on the invoice details page. ## Customer routing ### Default routing address Hyperline builds the customer's default routing address with scheme `0225` and their SIREN. It resolves the SIREN in this order: 1. **Registration number**: Hyperline uses a 9-digit SIREN directly or extracts the first 9 digits from a 14-digit SIRET. 2. **Tax ID**: if the registration number is missing or invalid, Hyperline extracts the SIREN from the customer's French tax ID. A customer has the SIRET `12345678900015`. Hyperline uses the first nine digits as its SIREN and routes the invoice to `0225:123456789`. ### Routing status When France PA is enabled on the invoicing entity, the customer page shows the routing address next to a live status resolved against the PPF directory: | Status | Meaning | | - | - | | **Checking** | Hyperline is querying the directory for the customer's routing address. | | **Registered** | The routing address exists in the directory. Invoices can be routed to the customer's PA. | | **Not found** | The directory has no entry for the resolved routing address. Search the directory to select the correct entry. | | **Missing** | Hyperline cannot infer a routing address from the customer's SIRET or tax ID. Add an override to set one. | | **Unavailable** | The France PA directory could not validate the routing address. Try again later. | ### Search the directory When the status is **Not found**, a **Search directory** button appears next to the routing address field in the customer edit form: 1. Open the customer details page. 2. Click **Edit** in the **Information** section. 3. Click **Search directory** next to **Custom e-invoicing routing address**. 4. Search by SIREN, SIRET, or tax ID (at least 9 characters). 5. Select the matching entry. Hyperline fills the field with its routing address. 6. Save the customer. ### Override the routing address If the customer uses a routing address different from their SIREN, you can override the inferred value: 1. Open the customer details page. 2. Click **Edit** in the **Information** section. 3. Enter the address provided by the customer or their PA in **Custom e-invoicing routing address**. The field is optional and shows the inferred address as a placeholder. 4. Save the customer. The value in **Custom e-invoicing routing address** replaces the SIREN that Hyperline would otherwise infer for France PA routing. France PA expects a routing address rather than a generic e-invoicing code, which is why the field is labelled accordingly when France PA is enabled on the invoicing entity. If the same customer is marked **Government affiliated** and the invoicing entity also has Chorus Pro enabled, the field is instead labelled **Service code**. Hyperline then uses it for Chorus Pro routing rather than France PA. ## Next steps * See the [e-invoicing overview](./overview) for supported countries and general transmission behavior. * Configure [Chorus Pro](./chorus-pro) for French public-sector customers. # E-invoicing overview Source: https://docs.hyperline.co/docs/invoices/einvoicing/overview Understand e-invoicing compliance with Hyperline: standardized digital invoice transmission across regions like the European Union and beyond. ## What is e-invoicing? E-invoicing, or electronic invoicing, is the process of sending bills and invoices digitally between buyers and sellers. It typically involves a standardized format that allows invoices to be issued, received, and processed automatically by the involved parties' financial systems. This standardization is crucial for compliance, especially in regions like the European Union, where certain standards for e-invoicing are mandated. ## Support in Hyperline Hyperline is **compliant with the e-invoicing standards** of the European Union. It can generate valid invoices in both PDF and XML formats, and automatically transmit issued invoices to the appropriate tax authority in the invoicing entity's country. Hyperline is proactively integrating this compliance into its product foundations. It partners with a third party that is compliant with local requirements to offer this service in each country as the e-invoicing mandate becomes mandatory. | Country | Format / platform | Requirement scope | Hyperline status | Auto transmission | | - | - | - | - | :-: | | **Italy** | **SDI (Sistema di Interscambio)** / **FatturaPA** | B2G, B2B, B2C | **Supported** | ✅ | | **France** | **[Chorus Pro](./chorus-pro)** / **CII** | B2G | **Supported** | ✅ | | **France** | **[PA](./france-pa)** / **Factur-X** | Domestic B2B and e-reporting | **Supported** | ✅ | | **Belgium** | **[Peppol](./peppol)** / **BIS Billing 3.0** | B2G and B2B | **Supported** | ✅ | | **Germany** | **[Peppol](./peppol)** / **BIS Billing 3.0** | B2G and supported B2B recipients | **Supported** | ✅ | | **Germany** | **XRechnung** | B2G | **Supported** | | | **Germany** | **ZUGFeRD** | B2B | **Supported** | | | **Portugal** | **SAF-T PT** / **AT (Autoridade Tributária)** | B2G, B2B (progressively enforced) | **Planned** | | | **Spain** | **FacturaE** | B2G | **Supported** | | | **Spain** | **VERI\*FACTU** | B2B | **Supported** | ✅ | ## Customer routing information Hyperline uses the customer's country, tax ID, and registration number to determine the default routing value for each e-invoicing system. You only need to provide an override when your customer uses a different identifier or requires additional routing information. | System | Value inferred by Hyperline | Optional customer field | When to complete it | | - | - | - | - | | **[Peppol — Belgium](./peppol#routing-in-belgium)** | Scheme `0208` and the enterprise number derived from the Belgian tax ID | **Peppol participant ID** | The customer uses a different registered participant ID | | **[Peppol — Germany](./peppol#routing-in-germany)** | Scheme `9930` and the customer's German VAT ID | **Peppol participant ID** | The customer uses another participant ID, such as a Leitweg-ID | | **[Chorus Pro](./chorus-pro#routing)** | The customer's SIRET | **Service code** | The public institution requires routing to a specific service | | **[France PA](./france-pa)** | Scheme `0225` and the customer's SIREN | **Custom e-invoicing routing address** | The customer uses a routing address different from their SIREN | | **SDI — Italy** | The recipient's SDI code cannot be derived from their tax ID or registration number | **SDI code** | Enter the 7-character code provided by the customer | These customer fields use the same underlying e-invoicing code, but Hyperline displays a label adapted to the selected system. To set a value or override, open the customer details page, click **Edit** in the **Information** section, then complete the field shown for that system. The label the field takes depends on which e-invoicing systems are enabled on the customer's invoicing entity, and whether the customer is marked **Government affiliated**: * **Service code**: when the customer is government-affiliated and Chorus Pro is enabled on the invoicing entity. Chorus Pro takes precedence over France PA for B2G customers. * **Routing address**: when France PA is enabled (and the customer is not routed to Chorus Pro). * **Peppol participant ID**: when Peppol is enabled. * **SDI code**: when the Italian SDI is enabled. * **Service code**: when Chorus Pro is enabled without France PA. * **E-invoicing code**: fallback label when none of the systems above are configured on the invoicing entity. For SDI, the customer's tax ID identifies the company but not its electronic delivery channel. The customer must provide their **SDI code** separately. For France PA, the field expects a **routing address** (typically the customer's SIREN, or another electronic address they have registered) rather than a generic e-invoicing code. In the customer edit form, the field is an optional override labelled **Custom e-invoicing routing address**, with the inferred address shown as a placeholder. ### France PA routing status When France PA is enabled on the invoicing entity, Hyperline checks the customer's routing address against the France PA directory and displays a status next to the routing address: * **Checking**: Hyperline is querying the directory. * **Registered**: the routing address exists in the directory. * **Not found**: the directory has no entry for the resolved routing address. A **Search directory** button appears next to the override field in the customer edit form. Search by SIREN, SIRET, or tax ID (at least 9 characters) and select an entry to fill the routing address. * **Missing**: Hyperline cannot infer a routing address from the customer's SIRET or tax ID. Add an override to set one. * **Unavailable**: the directory could not validate the routing address. Try again later. See [France PA routing](./france-pa#customer-routing) for details. Copy an override exactly as provided by the customer or their e-invoicing platform. For [Peppol](./peppol), you can verify the participant ID in the [Peppol Directory](https://directory.peppol.eu/public). ## Activation If your country already requires this standard, you can activate this capability in your settings. Some systems require pre-registration before starting the automatic transmission of invoices. Click the **Add credentials** button to provide the necessary information. You can then follow the status of the transmission for each invoice in the invoice details page. If automatic transmission is disabled for an invoicing entity, invoices will show a "Not supported" transmission status instead of tracking the transmission progress. ### Mark as transmitted If you handled the transmission outside of Hyperline (for example, by uploading the e-invoice manually to a tax authority's portal), you can record this on the invoice. Its status then reflects reality, and downstream behavior treats it as transmitted. The **Mark as transmitted** action is available on the invoice detail page when the e-invoicing transmission status is **Not transmitted** or **Failed**. Use it when: * Your invoicing entity does not have automatic transmission enabled, but you have transmitted the e-invoice through another channel. * An automatic transmission attempt failed and you completed it manually outside of Hyperline. Once marked, the transmission status switches to **Manually transmitted** and the transmission date is set to the moment you triggered the action. Hyperline then treats the invoice the same as an automatically transmitted invoice. It becomes **edit-locked**, so you can no longer modify its content, and the [customer notification](#customer-notification) rules described below apply. Marking an e-invoice as transmitted only updates its status in Hyperline. It does not send the invoice to any tax authority or e-invoicing platform. Make sure the invoice has actually been transmitted before using this action. ## Export e-invoices To download the generated PDF and XML e-invoice files for several invoices at once, use the [e-invoice export](../exports#e-invoice-export) from the invoice list. ## Customer notification When e-invoicing is enabled and the invoice is eligible for automatic transmission, Hyperline sends the ["Invoice to pay"](../../account/settings#email-settings) email notification when the invoice is transmitted to the e-invoicing system. It does not send it when the invoice is issued. This email indicates to the customer that the invoice has been transmitted and is ready to be paid. # Peppol Source: https://docs.hyperline.co/docs/invoices/einvoicing/peppol Send compliant electronic invoices to Belgian and German customers over the Peppol network with Hyperline using the Peppol BIS Billing UBL format. ## What is Peppol Peppol (Pan-European Public Procurement Online) is a standardized network that enables businesses to exchange electronic documents, including invoices, securely and seamlessly across borders. By connecting to the Peppol network, you can send legally compliant e-invoices directly to your customers' accounting systems, reducing manual processing, eliminating paper, and ensuring faster payment cycles. Peppol uses a four-corner model where certified Access Points handle the secure transmission of documents between parties. ## Setup Before sending invoices via Peppol, you need to register your invoicing entity with the Peppol network. Navigate to **Settings > Invoicing**, select the appropriate invoicing entity if you have multiple, enable **Peppol**, and enter your Peppol credentials. After uploading the required documents, the registration process can take up to 72 hours. Once your entity is registered, Hyperline automatically sends eligible invoices via Peppol. Hyperline transmits invoices using the Peppol BIS Billing UBL Invoice/CreditNote V3 format. ## Routing in Belgium By default, Hyperline uses Peppol scheme `0208` and the customer's enterprise number, derived from their Belgian tax ID without the country prefix. For example, the tax ID `BE0543547220` produces the participant ID `0208:0543547220`. If the customer uses a different registered participant ID, you can override the inferred value in **Peppol participant ID**. You can verify a customer's participant ID in the [Peppol Directory](https://directory.peppol.eu/public). ## Routing in Germany By default, Hyperline uses Peppol scheme `9930` and the customer's German VAT ID. For example, the VAT ID `DE987654321` produces the participant ID `9930:DE987654321`. If the customer uses a different identifier, such as a Leitweg-ID, enter the complete participant ID in **Peppol participant ID**. You can verify that the ID is registered and able to receive invoices in the [Peppol Directory](https://directory.peppol.eu/public). Peppol is a delivery network. The participant ID identifies where to send the invoice; it is separate from the invoice format, such as XRechnung. ### Test German Peppol delivery You can use the German federal **OZG-RE test recipient** to test delivery from Hyperline. You do not need an Invopop account. This tests German public-sector invoicing (B2G); it does not confirm that a particular business customer can receive your B2B invoices. Use Hyperline **test mode** and the OZG-RE **test environment** throughout. Never send test invoices from your production account. Use email addresses controlled by your team: Hyperline can send emails in test mode. **Current limitation:** the Hyperline invoice form does not expose the buyer reference required by OZG-RE. Setting the customer's **Peppol participant ID** does not also set this reference, and **Purchase order** is a separate field. You can prepare the test customer yourself, but you cannot currently complete this particular test entirely through the invoice form. Before finalizing, use the in-app chat to resolve the buyer-reference requirement. Do not send the invoice with a generated payment reference in its place. #### 1. Prepare your German invoicing entity 1. Switch to **test mode** from the account switcher. See [Sandbox and test mode](/docs/getting-started/sandbox) if the option is unavailable. 2. Open **Settings > Invoicing** and select your German invoicing entity. 3. Check your company name, German billing address, VAT number, and contact details. Use your company's details for sender registration, rather than inventing a VAT number. 4. Enable **Transmit invoices via Peppol** and complete the registration using the link shown in Hyperline. Wait until the registration status is `Registered`. Your sender must be registered in the test environment even if you have already registered it in production. Generating XRechnung or ZUGFeRD files alone does not enable Peppol transmission. #### 2. Register on the receiving test portal Create an account for your company on the [OZG-RE test portal](https://test.xrechnung-bdr.de/) and activate it using the email you receive. This is a separate account from production OZG-RE. OZG-RE publishes these [official test identifiers](https://e-rechnung-bund.de/en/faq/how-can-i-send-test-invoices-via-peppol-to-the-ozg-re-portal/): | Information | Test value | Where it belongs | | - | - | - | | Peppol receiver ID | `0204:99661-WEBSERVICEOZG-28` | Customer's **Peppol participant ID** | | Buyer reference / Leitweg-ID | `99661-WEBSERVICEOZG-28` | Invoice's buyer reference; see the current limitation above | A made-up VAT number is not a test destination. This recipient uses a Leitweg-ID, so do not enter either identifier as a VAT number. The German VAT numbers in sample invoices are not a substitute for a registered test receiver. #### 3. Create the test customer in Hyperline 1. Create a company customer named **OZG-RE Peppol test** in your test account. 2. Assign your German invoicing entity and complete the customer's German billing address. Both the issuing entity and customer must be in Germany for this Hyperline flow. 3. Open the customer details page, then **Information > Edit**. 4. Enable **Government affiliated**. This selects the German public-sector invoice requirements for Peppol. 5. Set **Peppol participant ID** to `0204:99661-WEBSERVICEOZG-28` and save. 6. Use an internal test mailbox for customer and invoice emails. #### 4. Prepare and send the invoice 1. From the test customer, click **Create Invoice**. 2. Select your German invoicing entity and EUR currency. 3. Add a line named **Peppol delivery test**, with quantity **1**, net price **100 EUR**, and **19% VAT**. Check that the totals are **100 EUR net**, **19 EUR VAT**, and **119 EUR total**. 4. Set a due date and save with **Create draft invoice**. 5. Before finalization, confirm that the invoice's buyer reference is exactly `99661-WEBSERVICEOZG-28`. If you cannot set or verify it, keep the invoice in draft and resolve the limitation above. A custom note, purchase order, or Peppol participant ID does not replace it. 6. Once the reference is confirmed, finalize the invoice. If your account requires approval, complete that approval first. Hyperline then processes the eligible invoice for Peppol transmission automatically. 7. Keep the invoice number and submission time for checking the result. See [Manage invoices](/docs/invoices/manage) for the invoice creation and approval steps. #### 5. Check the result Check the invoice's e-invoicing result in Hyperline. You can also use the invoice list's **E-invoicing** filter to find `Completed` or `Failed` invoices. An invoice that is awaiting payment is not, by itself, proof of Peppol delivery. For confirmation on the receiving side, consult OZG-RE's invoice status information for your submission. Its [FAQ](https://e-rechnung-bund.de/en/faq/) describes status tracking. However, its [portal tutorial](https://e-rechnung-bund.de/mediathek/tutorials/ozg-re/) states that Peppol submissions are processed separately and may not appear in the portal list. If you cannot find the invoice, ask OZG-RE sender support (linked from the tutorial) to confirm the test submission. Provide your sender details, invoice number, submission time, and test receiver ID. Do not upload the invoice manually as proof of Peppol receipt: that would test another delivery channel. | Check | Evidence to keep | | - | - | | Hyperline processing completed | Invoice number and e-invoicing result | | OZG-RE receipt confirmed | Receiving status or confirmation for the same invoice | | Invoice contents match | Supplier, invoice number, currency, net amount, VAT, and total | The end-to-end test is complete only when you have both successful Hyperline processing and confirmation of receipt with matching contents. If only Hyperline processing is confirmed, record the result as **receipt not yet confirmed**. No payment is required for this test. #### Troubleshoot the test | Problem | What to check | | - | - | | Sender registration is incomplete | Return to **Settings > Invoicing** in test mode and complete Peppol registration. | | Recipient cannot be found | Copy the full official receiver ID, including `0204:`, and check that you are using test mode. A production directory lookup does not verify a test recipient. | | Missing or incorrect buyer reference | The invoice needs the Leitweg-ID without `0204:`. Keep the draft until this requirement is resolved. | | Invoice was generated but no Peppol transmission occurred | Check that Peppol transmission is enabled, the customer is **Government affiliated**, both addresses are German, and the invoice is finalized. | | Invoice was rejected | Read the error before retrying. Check addresses, sender contact details, the buyer reference, and VAT totals. | | Invoice is absent from OZG-RE's list | Absence is not proof of failure; follow the receiving-side confirmation steps above. | For unresolved Hyperline errors, share the invoice number and displayed error through the in-app chat. See [Troubleshoot accounting and e-invoicing sync errors](/guides/troubleshooting-sync-errors). After testing, use each real customer's registered Peppol ID and required buyer reference in production. Keep the OZG-RE test identifiers in your test account only. ## Set a participant ID To set the Peppol participant ID manually: 1. Open the customer details page. 2. Click **Edit** in the **Information** section. 3. Enter the complete participant ID in **Peppol participant ID**, using the `scheme:identifier` format. 4. Save the customer. This optional value overrides the participant ID that Hyperline would otherwise infer from the customer's tax ID. ## Troubleshooting If a Peppol invoice fails, first verify the participant ID and routing scheme in the Peppol Directory. A valid tax ID is not always the same as a valid Peppol participant ID. For broader accounting and e-invoicing sync issues, see [Troubleshoot accounting and e-invoicing sync errors](/guides/troubleshooting-sync-errors). # Invoice emails Source: https://docs.hyperline.co/docs/invoices/emails Send automated invoice email notifications to customers in Hyperline when an invoice is issued, paid, or overdue, with customizable recipients. Use **Settings > Emailing > Customer emails** to select which invoice and credit note notifications Hyperline sends. You can enable separate notifications for invoices with manual or automated payment methods, paid invoices, payment failures, finalized credit notes, and settled credit notes. See [Customer automated emails](../account/emails#customer-automated-emails) for the full list. The recipient email corresponds to the one specified in the **Invoice emails** field on your customer page (located in the Information panel). If this field is not defined, Hyperline uses the main **Email** of the customer. Hyperline still generates zero-amount invoices for record-keeping and closes them automatically without attempting payment collection. These invoices do not trigger **Invoice to pay** or **Invoice paid** emails, even when enabled. ## Invoice ready to be paid Enable **Invoice to pay (manual payment)** to notify customers when an invoice with a manual payment method, such as bank transfer, is generated. The email includes the invoice PDF. Enable **Invoice to pay (automated payment)** separately if you also want to notify customers when an invoice with an automated payment method is generated. For bank transfers, the invoice includes the details selected by the invoicing entity's [bank transfer configuration](../account/invoicing-entities#configure-bank-accounts-for-bank-transfers). For invoices eligible for automatic [e-invoicing](./einvoicing/overview), Hyperline sends the invoice-to-pay notification when the invoice is transmitted to the e-invoicing system, rather than when it is issued. To learn more about payment reminders and the dunning process, see the [Invoice reminders article](./reminders). ## Invoice paid When **Invoice paid** is enabled, Hyperline sends this email with the PDF attached once an invoice is fully settled. This includes invoices settled after you use **Add payment** to record or allocate an offline payment. ## Credit note notifications Credit notes have their own notification settings: * **Credit note finalized**: sent when a credit note is finalized and not yet refunded. * **Credit note settled**: sent when a credit note has been applied. ## Preview and track emails Use **Settings > Emailing > Templates** to [preview invoice and credit note emails](../account/emails#preview-email-templates) in each language and for each invoicing entity. To inspect an email already sent, open **Audit logs > Email activity** and select it. You can review its recipients, status, saved content when available, and delivery history. See [Sent emails and delivery history](../account/emails#preview-sent-emails-and-delivery-history) for details and preview availability. To use your own email address, configure a [custom sending domain](../account/emails#custom-sending-domain) and [sender settings](../account/emails#sender-and-reply-to-addresses). ## Resend an invoice or credit note by email You can resend an invoice or credit note by email by clicking the **Resend by Email** button in the invoice dropdown. This button is available on both the [invoices list](https://app.hyperline.co/app/invoices/list) and the invoice page. Hyperline sends the appropriate email based on the invoice status. Hyperline asks you to confirm the action and reminds you of the email address it will be sent to. The **Invoice emails** address takes precedence over the customer's main **Email**. If everything looks good, click **Resend email** to send the email. Hyperline also adds an entry to the invoice's history. ## Email sending delay Hyperline sends invoicing emails right after the invoice is generated. The delay might vary slightly depending on the method. After actions such as checkout completions, payment errors, and manual charges, Hyperline sends the email immediately. When the billing schedule generates invoices automatically, the email can take up to 5 minutes to reach the customer. # Invoice exports Source: https://docs.hyperline.co/docs/invoices/exports Export Hyperline invoice data with built-in CSV exports (simple, accounting, or comprehensive formats) for bookkeeping and external analysis. If you wish to export your invoice data, especially for accounting purposes, Hyperline provides you with built-in and flexible file exports. ## Export flow On your [invoices page](https://app.hyperline.co/app/invoices), click the **Export invoices** menu in the top-left corner, then select **Export invoices**. Hyperline provides three export types: * **Simple export**: Export a single file with the details of your invoices. * **Detailed export**: Export two files with invoices and their line items in a zip file. * **Complete export**: Export invoices, their line items and the PDF files in one go. Select the start date and end date of data you want to export. Hyperline provides CSV, XLSX, or JSON format. Hyperline automatically downloads a file with the related data. ## E-invoice export If you use [e-invoicing](./einvoicing/overview), you can download the generated e-invoice files for a set of invoices in a single archive. Use this export to archive your e-invoices or share them with your accountant. On your [invoices page](https://app.hyperline.co/app/invoices), click the **Export invoices** menu, then select **Export e-invoices**. Select the start date, end date, and timezone of the invoices to export. The end date must be on or after the start date. The export also applies the filters currently set on the invoice list. Hyperline generates a ZIP archive containing: * The available e-invoice PDF and XML files for the matching invoices. * A status summary listing invoices whose e-invoice is missing or unavailable. The e-invoice export has no export type or file format to select. The file downloads automatically once it is ready, and it is also available in **Reports** > **Exports**. ## Large exports Hyperline generates invoice exports asynchronously. On large workspaces or broad date ranges, the file can take longer to prepare before it is available to download. CSV exports are limited to 10,000 rows. If your export is too large, reduce the date range, export a narrower invoice set, use the public API for paginated extraction, or contact support for help with a bulk export. ### Amounts format The exported amounts are represented in the currency's smallest unit. For **European currencies**, this means that amounts are represented in **cents**. If you want to convert the exported amount into its decimals format you need to divide it by `100`. For example, an exported amount of `3417` (Euro, a two-decimal currency) will correspond to `€34.17`. The same logic applies for **zero-decimal currencies** and **three-decimal currencies**. In this case, you need to apply the right multiplier (or none). For example, an exported amount of `12065` (West African CFA franc, a zero-decimal currency) will correspond to `F CFA 12065`. # Public invoice page Source: https://docs.hyperline.co/docs/invoices/invoice-page Share a hosted public invoice page where customers can view, download, and pay outstanding or paid invoices through a secure Hyperline link. ## Overview Hyperline provides an invoice page where your customers can access both outstanding and paid invoices. This public page is also linked in the "Invoice to pay" email sent. You can access this page from the invoice details page in your Hyperline interface. ## Pay invoice Customers can pay their invoices directly through the public invoice page which acts as a payment link, similar to the checkout process. When the payment method allowed is credit card or direct debit, customers can enter their payment information to pay the invoice instantly. When the allowed payment method is bank transfer, customers can view and download the invoice with the bank transfer details included in the payment information section. ## Paid invoice Once an invoice is paid, the page will display the PDF invoice along with the date and payment method used. Customers can download the invoice using the button on the top right. ## Explore consumption For invoices containing metered products (usage and connected seats), customers can explore the details of every event billed during the period with full context. Additionally, they can export this data: * **Export single product**: Click the export button within a specific product's event table to download a CSV file containing only that product's events * **Export all products**: Click **Download all events** on the top-right corner to download a ZIP file containing separate CSV files for each product on the invoice # Manage invoices Source: https://docs.hyperline.co/docs/invoices/manage Create, edit, and duplicate Hyperline invoices manually for ad-hoc billing needs that fall outside subscription or recurring payment flows. While most invoices are automatically generated from subscriptions or one-time payments, Hyperline provides full flexibility to manually create, edit, and duplicate invoices for specific business needs. ## Create invoice Manual invoice creation is useful for ad-hoc billing needs that fall outside your standard subscription or payment flows. From the customer details page, click **Create Invoice**. ### Configuration Configure the header information and details of the invoice. * **Issue date**, for legal compliance, Hyperline automatically sets the issue date to today's date, and you cannot modify it. * **Due date**, set any future date (including today) as the due date. Once reached, the invoice status will change to `late`, similar to the payment delay functionality. * **Purchase order**, optionally add a custom purchase order reference to the invoice. * **Custom note**, optionally include additional information for your customer in a custom note field. * **Link subscription**, optionally attach an invoice to a subscription for reporting purposes. ### Line items Line items represent the products and services on the invoice. Customize the name, description, billing interval, and tax rate for each of them. Hyperline calculates the total price automatically by multiplying quantity by unit price. You can also reference an existing product from your catalog. For usage-based products, retrieve the current usage for the invoice period by clicking the database icon in the quantity field. Note that pricing is not computed automatically when using catalog products. Using a catalog product enables your customer to explore consumption details for that product during the invoice period on the customer portal. Line items can have negative amounts to represent credits or adjustments. Note that the total invoice amount cannot be negative. ### Custom properties If you have created custom properties for invoices, you can fill them when creating or editing an invoice. Use invoice custom properties to keep structured information such as a contract reference, sales owner, internal cost center, or any value that should follow the invoice through reporting and integrations. When an invoice is generated from a subscription, Hyperline automatically copies the subscription's custom property values to the invoice when the same custom property is available on both entities. You can still edit the invoice value afterward when the invoice can be updated. ### Delete or re-order line items You can remove line items from the invoice, or re-order them to match the order of your choice. Re Order Or Delete ### Apply coupons Coupons reduce the invoice total before taxes. When creating or editing a draft invoice, you can select an existing coupon from your catalog or create an inline coupon for that invoice only. 1. In **Coupons**, click **Add coupon**. 2. Select a catalog coupon, or select **Inline coupon**: * **Catalog coupon**: reuse a coupon created in **Catalog** > **Coupons**. Its name and fixed amount or percentage discount are filled in automatically and cannot be edited on the invoice. See [Coupons](../coupons/overview) to configure reusable discounts. * **Inline coupon**: enter a custom name and a fixed discount amount in the invoice currency. This does not create a reusable coupon in your catalog. 3. Review **Line items** to select which invoice lines receive the discount. Leave the selection empty to apply it to all line items. For catalog coupons restricted to specific products, matching invoice lines are selected automatically. The catalog selector excludes expired coupons and coupons in an incompatible currency. You can only select a coupon restricted to specific products if the invoice includes a matching catalog product. You cannot select the same catalog coupon twice on one invoice. The discount cannot exceed the total amount of the line items it applies to. Apply an existing 10% partner coupon to an implementation fee, or select **Inline coupon** to give a customer a one-time €50 discount on that invoice. ### Create draft Click **Create draft invoice** to generate the invoice with `draft` status. Hyperline doesn't send draft invoices to customers, and you can edit them multiple times before finalizing them manually. ### Require approval before finalization You can require internal approval before a draft invoice is finalized. See [Invoice and credit note approvals](/docs/invoices/approval) to configure the applicable flow, submit a document for review, and handle requested changes. ## Edit invoice Edit invoices to modify information before sending them for payment. This provides full control over the final invoice content. Once an invoice has been emitted, some elements like issue date, line items and coupons cannot be edited anymore due to legal requirements. You can edit customer billing details, custom note, and purchase order even after the invoice is marked as paid. ## Duplicate invoice Duplicate existing invoices to quickly create similar invoices or correct errors in finalized invoices. It's the right approach to: * Quickly replicate a payment for another period * Correct errors in a finalized invoice by creating a new version * Reuse invoice structure with updated information Duplicated invoices automatically reflect any updates to the customer's address or tax rate. If the original invoice had a bank account that has been deleted, the duplicated invoice will not include a bank account reference. ## Common validation errors When creating, editing, or duplicating invoices, you may encounter validation errors. Here are the most common ones and how to resolve them: **Missing required information** * **Missing customer ID**: Ensure a customer is selected before creating the invoice. * **Missing currency**: Select a currency for the invoice. * **Missing line item name**: All line items must have a name. * **Missing line item unit amount**: All line items must have a unit amount specified. * **Missing coupon amount**: Enter a fixed discount amount for each inline coupon. Catalog coupons use their configured fixed amount or percentage discount. **Date and status issues** * **Issue date cannot be in the past**: When creating invoices, the issue date must be today or later (except when duplicating). * **Settlement date can only be set for paid invoices**: Only invoices with `paid` status can have a settlement date. * **Settlement date is required for paid invoices**: Invoices marked as `paid` must include a settlement date. **Address and tax issues** * **The address is not complete enough for tax declaration**: Ensure the customer's billing address includes all required fields for tax compliance. * **Customer name is required for tax calculation**: The customer must have a name for tax calculations to work properly. **Product and invoice references** * **Product not found**: The referenced product may have been deleted. Select a different product or remove the product reference. * **Duplicate invoice found**: An invoice with the same details already exists for this customer. * **Some invoices don't exist or are already linked to another invoice**: When linking invoices, ensure all referenced invoices exist and are not already linked. **Payment provider issues** * **Failed to retrieve provider transaction**: There was an issue connecting to the payment provider. Try again or contact support. Is something still unclear? Don't hesitate to reach out to our team via the in-app chat if you need additional support. # Invoices overview Source: https://docs.hyperline.co/docs/invoices/overview Automate recurring invoicing and create one-off invoices in Hyperline, with automatic line items from subscriptions, multi-currency support, and PDFs. ## Invoices in Hyperline Hyperline provides a simple and versatile invoicing solution to automate your invoicing, no matter the pricing model or the currency. Automate recurring billing or create one-off invoices on demand for your customers. Hyperline automatically computes line items for invoices corresponding to products in the assigned plan. You manage invoices in the **Invoices** section of Hyperline. You can [configure your invoice](./configuration) in the Settings pages. Invoice numbers always follow a sequential pattern (learn more in the [invoice configuration](./configuration#invoicing-number)). Invoices always feature: * A creation date * A due date * The invoice status * The invoice category * The payment method * The total amount for the transaction, including VAT if applicable * Names and addresses of both parties * Legal information (if any were added in the [Invoice settings](./configuration)) ### Invoice language Hyperline invoices are currently available in **English, French, German, Italian, Spanish, Polish, Portuguese and Dutch** languages. Hyperline generates the invoice in the primary language of your country for legal and accounting purposes. However, depending on your customer's language preference, you or they can download the invoice in their preferred language. ### Invoice customer address Invoices created before changing a customer's address will keep the previous address. Any change made to an invoice through the **Edit** action will automatically update the customer's address. ### Invoice payment method Hyperline uses the customer's default payment method when creating an invoice. While an invoice is not paid, you can update it. ### Invoice status `Draft` Represents an editable invoice. Hyperline only uses this status before the invoice is finalized (ready to pay). A draft invoice is generated without a number. `Open` Displays when your customer is assigned a metered subscription. Hyperline creates an open invoice (generated without a number) in the background and updates it regularly to represent the latest consumption. `Grace period` Displays when a metered subscription has closed. During the grace period, the invoice isn't charged, and you can make modifications manually until the end of the grace period. A grace period invoice is generated without a number. `To pay` The invoice is finalized (a number is assigned) and is pending payment. Hyperline automatically charges invoices attached to an automated payment method. Invoices paid by bank transfer remain in this status until [you mark them as paid](./reconciliations). `Late` The invoice has passed its due date and has not been fully paid yet. This status helps you identify overdue invoices that require follow-up. `Partially paid` The invoice has been paid only partially (only for transfers). See the [Reconciliation page](./reconciliations) for more details. `Paid` The invoice is fully paid and now has a settled date. You can book-keep it. `Pending consolidation` The invoice is held, waiting to be merged into a daily consolidated invoice for a customer that has [consolidated invoicing](./consolidated-invoicing) enabled. It has no invoice number yet and hasn't been charged. `Consolidated` The invoice was merged into an aggregate consolidated invoice. It links to the aggregate via `linkedInvoiceId`. Hyperline keeps the source for record-keeping and charges the aggregate. Learn more in [consolidated invoicing](./consolidated-invoicing). `Missing payment info` Hyperline hasn't tried to process the invoice because the related customer doesn't have a payment method. `Error` Payment failed and no automatic retries or eligible fallback methods remain, or the failure requires manual action. Learn more about [handling payment errors](../payments/payment-errors). `Uncollectible` Represents an invoice that cannot be collected due to reasons like bankruptcy, disputes, or prolonged nonpayment. Marking an invoice `uncollectible` keeps it in this status for record-keeping, cancels future scheduled automated payments, and triggers the accounting write-off for its outstanding balance. It does not refund or reverse settled payments through the payment provider. An invoice cannot be marked `uncollectible` while a payment is processing, but it can still be marked as paid if funds are collected later. `Voided` The invoice has been voided and is no longer valid. Voided invoices are kept for record-keeping purposes but have no financial impact. `Closed` The invoice has been closed without payment, typically because there was nothing to bill after the grace period ended (for example, when all metered items resulted in zero usage). ### Invoice categories **Refund** - The related payment has been refunded. A credit note has been issued. **One-off** - Describes a one-off invoice. **Subscription** - Describes an invoice that is part of a subscription. You can filter invoices by category in the **Invoices** page using the **Category** filter dropdown. ### Invoice filters **Outstanding** - Invoices that have been only partially paid and are still awaiting payment. **Late** - Invoices with past due date and not fully paid yet. **Paid** - Fully paid invoices. **Refunded** - Refunded invoices. ### View invoices by customer You can view all the invoices for a specific customer by going to **Customers**, selecting one customer and clicking the **Invoices** tab. ### Accounting If the [accounting module](/docs/accounting/getting-started) is enabled, the invoice detail page carries an **Accounting** section showing how that invoice was recorded in your books: * The **journal entries** posted for it: at issue, at settlement, and on any credit note * The **recognition schedules** created for its line items, when revenue is deferred Where an invoice's entity has more than one ledger, a selector lets you switch between them. The same invoice can post to a statutory and a management ledger with different accounts. **View in ledger** on any entry opens it in the [journal entry lines](/docs/accounting/entries#journal-entry-lines-drill-down) view, in the context of the account it posted to. ## Send recurring invoices Hyperline automatically generates recurring invoices from subscriptions. For this, you need to [assign a subscription](../subscriptions/create) and start a subscription to a customer to trigger recurrent invoicing. Recurring invoices can have different amounts or the same amounts each time, depending on the pricing model (pay-per-use is more likely to vary over time than monthly fixed-price subscriptions). ## One-time payments Hyperline generates one-off invoices for one-time payments, such as onboarding fees, unique license fees or any other product you create from the **Product catalog** section. Whatever its usual pricing model, the product is charged as a fixed amount (quantity × unit price). To charge a one-time payment: Select the customer you want to charge.
  • Immediately: The date will be set to today, and result in a direct charge on your customer's payment method
  • Checkout completion: It will create a checkout link for your customer to pay with. The issue date will match the payment date
If none are set by default, you can still visit the **Product catalog** page to create new products. 1. If you select **Immediately**, the invoice is created instantly and will appear with a **Paid** status. 2. If you enabled the checkout session, Hyperline creates an invoice with a **Draft** status until the customer pays through their checkout page.
You can generate one-time payment invoices for a customer who already has an ongoing subscription with recurring invoices. Alternatively, you can generate one-time payment invoices for a customer without an active subscription. # Reconciliation Source: https://docs.hyperline.co/docs/invoices/reconciliations Reconcile invoices with banking transactions in Hyperline: automatic matching for PSP card and SEPA payments, plus bank statement import. Hyperline natively supports reconciliation between banking transactions and invoices in multiple ways, depending on the payment method used by your customers. ## Payment service provider (PSP) If you use a Payment Service Provider (PSP) with automated payment methods like cards or direct debit, invoices will automatically reconcile without manual intervention. As Hyperline orchestrates the payment initiation, it tracks payment status (money movement, chargebacks, etc.) in real-time and updates the invoice accordingly. ## Connected bank account Hyperline **supports a wide range of bank connections in France, the UK, Germany, Belgium, Spain, and the US**, enabling you to link your business bank account with a single click. Once connected, you can add your bank account details to invoices, and Hyperline will **automatically suggest matching transactions for each invoice, facilitating easy reconciliation**. Click **Connect bank account**. Click **Link new bank** and complete the authentication process. Once linked, select the bank account you want to connect to Hyperline. Hyperline will automatically match transactions or suggest one from your bank account for each unpaid invoice based on matching details. Additionally, you can access your bank statements and account balances, and reconcile invoices directly from the Transactions page. ### Reconciliation logic Reconciliation targets invoices with status `to_pay` or `partially_paid`, and is restricted to payment methods `transfer` or `external` (or no payment method set). Hyperline automatically matches incoming bank transactions to outstanding invoices using a confidence-based scoring system. Each transaction is scored against unpaid invoices, and only matches above a minimum confidence threshold are suggested, ranked from most to least likely. Matching signals (from strongest to weakest): * Payment reference: if the transaction description contains the invoice's payment reference, it's an automatic match. * Alphanumeric invoice number: invoice numbers containing both letters and digits (e.g. INV-2024-042) found in the transaction description are also treated as certain matches. * Known payer account + exact amount: when the paying bank account is already linked to the customer and the amount/currency match, confidence is very high. * Invoice number, customer name, amount: these signals are scored individually and combined. An invoice number appearing as a distinct word carries more weight than a partial match. Customer name and exact amount each contribute additional confidence. Only matches exceeding the confidence threshold are surfaced, sorted by likelihood so the best match appears first. Hyperline fetches transactions daily, so a transaction arriving in the bank account on one day is suggested for reconciliation the following day. ### Viewing invoice status in transactions When viewing your bank transactions, Hyperline displays invoice status indicators next to reconciled or suggested invoices. These visual indicators help you quickly identify the payment status of each invoice. This makes it easier to understand the current state of each invoice directly from the transactions view without needing to navigate to the invoice detail page. ## Automated customer bank transfer Hyperline offers a method to **automate bank transfer reconciliation** by assigning unique bank account details per customer and a distinct reference for every invoice. The account details remain constant for each customer, while the reference changes with each invoice. Hyperline adds the bank account details and reference to the invoice **when it is ready to be paid** and sent for payment. When a payment is received with the matching reference, Hyperline automatically reconciles the invoice and marks it as paid, eliminating the need for manual intervention. If a customer uses an incorrect or unrecognized reference, the funds are automatically returned to the customer's bank account. This feature is currently available only with Mollie. You can transfer payouts from your Mollie account to another bank account, just as you would with any other card or direct debit payments. ## Manual customer bank transfer If you enable manual bank transfers as a payment option in **Settings** > **Payment**, record or match the payment after the funds are received. Hyperline then derives the invoice status from the resulting transaction allocation. After setting up a subscription for your customer, they can pay via their checkout page by selecting **Bank transfer**. When the customer clicks **Pay**, Hyperline shows them a link to download their invoice as a PDF document. The invoice will then appear in the **Invoices** section with the status **To pay**. Use **Add payment** once the payment is received. Hyperline marks the invoice as **Paid** or **Partially paid** according to the amount allocated. ### Add a payment manually Recording an offline payment only applies to bank transfers and other payments received outside Hyperline. Cards, direct debits, and automated transfers processed through a payment provider update invoices automatically. When you create a new subscription with bank transfers, Hyperline automatically sets the invoice status to **To pay** until the first payment is received from the customer. Open the invoice, select **Actions** > **Add payment**, then select the source: * **Use wallet balance** to debit the customer's wallet * **Use existing transaction** to match a compatible transaction that still has an unallocated amount * **Record offline payment** to record a bank transfer or another payment received outside Hyperline Enter the amount and click **Add payment**. Hyperline creates or updates the allocation, then derives the invoice's **Paid** or **Partially paid** status from the amount settled. When recording a new offline payment, only **Bank transfer** and **External payment method** are available. The connected payment provider must process card and direct debit payments. If a card payment happened outside Hyperline, use **External payment method**. You can add several payments to the same invoice. Each transaction keeps its own amount, and the invoice becomes fully paid only when its remaining amount reaches zero. If the transaction amount exceeds the invoice amount left to pay, Hyperline allocates only the maximum valid amount. The remainder stays unallocated, and you can assign it to another invoice or add it to the customer's wallet. See [Understand payment allocations](/docs/payments/allocations) for the difference between unallocated transactions and wallet funds. Below is an example of a partially paid invoice: And a fully paid invoice: # Credit notes & refunds Source: https://docs.hyperline.co/docs/invoices/refunds Issue credit notes and process refunds in Hyperline: cancel charges, return funds via the original payment method, or top up customer wallets. If you are looking to cancel subscriptions, please visit the [manage subscriptions page](/docs/subscriptions/manage). It's currently not possible to create a credit note for an invoice not created by Hyperline.
As an alternative, you can [provide a free top-up on your customer's wallet](/docs/wallets/balance), which Hyperline uses to pay future invoices.
## Choose the right action Hyperline separates the accounting correction from the money movement: * **Create a credit note** when an invoice amount must be cancelled or reduced. The credit note is the legal/accounting document. It can be created without money movement, or it can be settled by refunding the original payment method, crediting the customer wallet, or recording an external refund. * **Refund a transaction directly** when a settled PSP payment must be sent back but the invoice should remain payable. This creates a refund transaction for the full remaining refundable amount. It does not create a credit note or cancel any invoice amount. Once the refund settles, the related invoice payment status is recalculated and can go back to **to pay**. These movements are connected through allocations. Allocations determine which document each amount currently affects and preserve previous relationships when they change. See [Understand payment allocations](/docs/payments/allocations) for the complete model. | Situation | Use | | - | - | | Cancel or reduce an invoice amount | Create a credit note | | Cancel or reduce an invoice amount and send money back now | Create a credit note and enable **Refund transaction** | | Record money already refunded outside Hyperline for a cancelled or reduced invoice | Create a credit note and select **Mark as refunded outside of Hyperline** | | Send a captured payment back while keeping the invoice due | Refund the transaction directly | | Settle a credit note that was created without a refund | Open the credit note and select **Add refund**. See [Refund an open credit note](#refund-an-open-credit-note) | | Record a refund already sent outside Hyperline without cancelling any invoice amount | Record an offline refund from the customer's **Transactions** page, optionally linked to the original payment. See [Understand payment allocations](/docs/payments/allocations#record-a-transaction-received-outside-hyperline) | | Credit a customer for an invoice not created by Hyperline | Create an ad-hoc credit note or provide a wallet top-up | ## Configuring your credit notes Credit notes are generated manually or when you create a credit note from an invoice. You can customize the credit note template in the **Settings > Invoicing** section. ### Set the default refund destination When Hyperline creates a credit note automatically, for example during a subscription update, the settings of the invoicing entity determine what happens to the credited amount. Go to **Settings** > **Invoicing entities**, open the relevant entity, then go to **Invoicing** > **Credit notes**: * When **Refund credit notes to wallet by default** is enabled, Hyperline adds the amount to the customer wallet. Wallets must also be enabled in **Settings** > **Wallets**. * When it is disabled, Hyperline refunds the original payment method if the invoice was paid automatically, for example by card or direct debit. For an invoice paid by bank transfer, the credit note remains open and no funds are moved automatically. When you select a refund method while creating a credit note, your choice takes priority over this default. You have access to: * The **credit note number** pattern. * The available variables are: `number`, `YYYY`, `MM`, `DD`. * `number` is mandatory. * The **next credit note number**. This is a read-only field that shows the next credit note that will be generated. If you want to update the value, please contact our support team. * The **credit note legal information**. This field is optional. * The additional **credit note footer**. This field is also optional. By clicking the globe on the right side of the text area, you can translate both the legal and additional information into multiple languages. Hyperline automatically selects the relevant language when it generates the credit note. Credit note settings with translation options ## Create a credit note You can create a credit note from any invoice with the following statuses: **paid**, **partially paid**, **to pay**, or **error**. **Prerequisites and restrictions:** * You cannot create a credit note for an invoice that has already been fully credited (indicated by the `refundedAt` timestamp) * If an invoice has been partially credited, you can create additional credit notes up to the remaining amount available for credit notes * You cannot create credit notes for invoices imported from external billing systems (see [Ad-hoc credit notes](#ad-hoc-credit-notes) for alternatives) Click the invoice you want to create a credit note for. A modal will open with the credit note creation form. ### Credit note options The creation modal includes the following options: #### Partial credit note By default, the credit note is created for the full invoice amount. Enable this option to create a partial credit note by selecting specific line items. When enabled, a table displays all line items from the original invoice with the following columns: | Column | Description | | - | - | | Selected | Checkbox to include the line item in the credit note | | Unit amount excluding tax | The unit price before tax | | Unit count | The quantity to credit | Partial credit note line items selection table You can adjust both the quantity and the unit amount for each selected line item. The credited amount cannot exceed the original line item amount minus any amounts already credited for that line item. If the invoice contains both credit and debit line items (including negative line item amounts), line item selection is not available. In this case, you can only specify a single amount to credit. When creating a partial credit note, you must select at least one line item before submitting. The form will display an error message if you attempt to create a partial credit note without selecting any line items. **Maximum credit note amount calculation:** The maximum credit note amount is calculated as the total invoice amount minus the sum of all non-voided credit notes already issued. Voided credit notes are excluded from this calculation, allowing you to create new credit notes if a previous one was voided. The total credit note amount cannot exceed the maximum credit note amount for the invoice. If you attempt to credit more than the available amount, the system will prevent you from creating the credit note. #### Send credit note via email When enabled, Hyperline emails the credit note to the customer when you create it. This option is checked by default but only available if the customer has an email address configured for invoices. #### Refund transaction Enable this option to settle the credit note with a money movement. The availability of refund methods depends on the invoice status and payment method. **Refund availability by invoice status:** * **Paid invoices**: All refund methods are available (subject to additional restrictions below) * **Partially paid, to pay, or error invoices**: The refund transaction option is disabled. You can only create a credit note without processing a refund **Available refund methods:** * **Refund on original payment method**: Initiates a refund to the payment method used for the original invoice. When you execute a refund, Hyperline sends the refund request to your payment provider. The success notification indicates the refund has been **initiated**, not that funds have been transferred. The payment provider processes the refund asynchronously. Funds are returned to the customer according to the provider's timeline (typically immediately for card payments, or within 3-4 days for bank transfers). Available when: * The invoice status is **paid** * The invoice was paid using an automatic payment method (not bank transfer) * The invoice has not been previously refunded * For GoCardless transactions: At least 7 days have passed since the invoice settlement date Monitor your payment provider dashboard for the final refund status and confirmation that funds have been transferred to the customer. You cannot refund a payment while it has an active chargeback. See [Chargebacks](/docs/payments/chargebacks) to understand how disputes affect payments and invoice balances. * **Refund on customer wallet**: Adds the credited amount to the customer's wallet balance. Available when: * The invoice status is **paid** * Wallets are enabled in your settings * For invoices paid via bank transfer, this is the primary refund method available * **Mark as refunded outside of Hyperline**: Creates a record of an external refund transaction. Available for paid invoices when automatic refund methods are not available or when you prefer to handle the refund manually Refund transaction method selection options If you do not enable the refund transaction option, the credit note is created without any money movement. This is useful when you only need the accounting document or when you plan to process the refund separately. **GoCardless refund delay**: For invoices paid via GoCardless, you must wait 7 days after the invoice settlement date before processing a refund through the original payment method. During this waiting period, you can create the credit note and either mark it as refunded externally or refund to the customer's wallet (if enabled). ## Refund an open credit note A credit note created without a refund transaction keeps a remaining balance. You can settle that balance later from the credit note itself. Open the credit note and select **Actions** > **Add refund**. The same **Add refund** button appears in the credit note's **Transactions** section while no transaction is recorded yet. The action is available while the credit note has a remaining balance and no pending transaction. Depending on the customer's situation, the modal offers up to three options: 1. **Top up wallet** adds the refund amount to the customer's wallet and links it to the credit note. This option is available when the customer has a wallet in the credit note's currency. 2. **Use existing refund** allocates all or part of an existing refund transaction that still has an unallocated amount. 3. **Create new refund** records a refund made outside Hyperline. Select the refund date, the refund method (bank transfer or external payment method), and the amount. The first available option is selected automatically. The amount defaults to the credit note's remaining balance and cannot exceed it. Lower the amount to settle the credit note partially, for example to top up the wallet with only part of the balance. Confirm with **Add refund**. Wallet top-ups from a credit note appear in the wallet's funding history and remain linked to the credit note. See [Understand payment allocations](/docs/payments/allocations#credit-note-allocations) for how Hyperline tracks the amounts used across invoices, refunds, and wallets. ## Invoice status changes When you create a credit note, the status of the original invoice changes based on its current state: * **To pay invoices**: Creating a credit note automatically voids the original invoice, unless the invoice has a pending payment transaction (`to_process`, `pending`, or `scheduled` status). If a payment transaction is pending, the invoice will not be voided to prevent conflicts with the ongoing payment process. The invoice status changes to **voided**, and it can no longer be collected. The invoice remains visible in your system for audit and compliance purposes. **Irreversible action**: Once an invoice has been voided due to a credit note creation, you cannot reverse this action. If you need to correct a credit note, you can void the credit note itself and create a new one, but the original invoice will remain voided. * **Paid invoices**: The invoice status remains **paid**, but the system tracks that a credit note has been issued. The invoice displays an indicator showing that a credit note has been created. * **Partially paid invoices**: The invoice status remains **partially paid**. The credit note reduces the amount that can be credited in the future, but does not change the invoice's payment status. * **Error invoices**: The invoice status remains **error**. You can create credit notes to resolve billing discrepancies. ## Credit note lifecycle ### Require approval before finalization You can require internal approval before a draft credit note is finalized. See [Invoice and credit note approvals](/docs/invoices/approval) to configure the applicable flow, submit a document for review, and handle requested changes. ### Void a credit note You can void credit notes if they were created in error or need to be corrected. When a credit note is voided: * The credit note status changes to **voided** * Voided credit notes are excluded from credit note amount calculations * You can create new credit notes up to the full invoice amount (minus any other non-voided credit notes) * The voided credit note remains visible in the system for audit trail purposes * The original invoice status is not automatically restored when a credit note is voided To void a credit note, navigate to the credit note detail page and use the void action from the actions menu. **Voiding paid credit notes:** A paid credit note means the credit note itself has been settled, for example through a PSP refund, a wallet credit, or an external settlement. You can still void it when the accounting document needs to be corrected. Voiding a paid credit note does not reverse the money movement. You need to manually handle any necessary adjustment with your payment provider, wallet balance, or customer. You can void credit notes regardless of their status, including paid credit notes and credit notes that have been applied to other invoices. Void credit note action in the three-dots menu ## Visualize your credit notes To view and manage your credit notes: From there, you can: * Download credit notes as PDF files * View associated transactions on payment service providers (PSPs) * Access credit note details and history * Void credit notes if needed All actions are available through the actions menu for each credit note. Credit notes list with available actions menu Credit notes are linked to their original invoices. You can view this relationship from either the invoice or credit note detail pages. The invoice detail page shows all associated credit notes, while the credit note page displays the original invoice under **Reference invoice**. When a credit note's amount is allocated to other invoices, the credit note detail page also shows an **Applied invoices** row. It lists each invoice the credit note is applied to, with the amount allocated to it. The **Reference invoice** row keeps pointing to the invoice the credit note was created from, even when the amount is applied elsewhere. Credit note detail page showing link to original invoice ## Ad-hoc credit notes Ad-hoc credit notes are standalone credit notes that are not linked to an existing invoice in Hyperline. This feature is useful when you need to issue a credit note for an invoice created in a different billing system. It's also useful when you provide a credit that doesn't correspond to a specific invoice. **Key characteristics:** * Not automatically applied to any invoice (manual application required if you want to offset amounts) * Do not affect the credit note amount calculations of existing invoices * Can be sent to customers via email * Follow the same template configuration as regular credit notes To create an ad-hoc credit note, use the **Create invoice** button in the customer details page. ### Allow credit notes without an invoice You can turn off ad-hoc credit notes per invoicing entity. In **Settings** > **Invoicing entities** > *entity* > **Invoicing** > **Credit notes**, the **Allow credit notes without an invoice** switch controls whether you can create standalone credit notes for that entity. The setting is **allowed** by default. When the setting is disabled for an invoicing entity: * The global **Create new** menu shows **Invoice** as the entry point instead of the combined invoice/credit note label. Create credit notes from an existing invoice as described in [Create a credit note](#create-a-credit-note). * The invoice editor hides the **Credit note** document type when you select that entity. If a draft is already set to **Credit note** and you switch to an entity where standalone creation is disabled, the type resets to **Invoice**. * Existing credit notes for the entity remain visible. You can still void or download them regardless of the current setting. The **Credit note** document type stays available in the invoice editor when you edit an existing credit note, so you can still finish previously created drafts. # Invoice reminders & dunning Source: https://docs.hyperline.co/docs/invoices/reminders Configure invoice reminder audiences, eligible invoices, and email schedules, including follow-ups after failed payments or chargebacks. Use reminder sequences to email customers before, on, or after an invoice's due date. Each sequence defines an **Audience**, the **Invoices** to include, and the **Emails** to send. Reminders ask customers to settle an outstanding balance. They are separate from [automatic payment retries and payment method fallback](/docs/payments/payment-errors), which attempt to collect payment, and from [payment failure notifications](/docs/account/emails#customer-automated-emails). ## Configure a reminder sequence 1. Go to **Invoicing > Reminders**. 2. Open an existing sequence or click **New sequence**. 3. Enter a **Name** and, optionally, a **Description**. 4. Configure **Audience**, **Invoices**, and **Emails** as described below. 5. Click **Save changes** and check that the sequence is **Active**. For an inactive sequence, use **Actions > Activate**. The default sequence starts inactive, with reminders seven days before the due date, one day after, and seven days after. Its initial copy follows the default invoicing entity's language where supported, with English as the fallback. Review the audience and email content before activating it. ### Audience Select which customers the sequence applies to. Matching the audience does not mean every invoice is eligible: the invoice must also meet the conditions in [Invoices](#invoices). * **Segment**: select an existing [customer segment](/docs/customers/segments), or create one. Eligibility follows the customer's segment membership as it changes. * **Custom**: filter by **Customer language** and [custom properties](/docs/properties/overview). Select **All** to match any customer language. All configured custom property conditions must match. The audience preview shows customer counts, not invoices scheduled for an email. A customer in the audience still needs reminders enabled to receive them. Hyperline selects one active sequence per customer. A matching segment sequence takes priority over custom audiences. If several segment sequences match, the oldest sequence takes priority. For custom audiences, Hyperline prioritizes the customer's language over **All**, then audiences with more custom property conditions. Use distinct audiences to keep the selection predictable. Language filtering selects customers; it does not translate the subject or body you write. Create separate sequences with the appropriate copy for each language. ### Invoices By default, reminders apply to unpaid or partially paid invoices that have: * No payment method assigned. * A bank transfer payment method. * An automatic payment method, such as a card or direct debit, marked as errored or expired. An **invoice** in `error` is different from an invoice whose **payment method** is errored or expired. The former requires the option below; the latter is already included when the invoice is awaiting payment or partially paid. #### Include invoices with payment issues Turn on **Include invoices with payment issues** in the **Invoices** section to also include: * Invoices in `error` after payment collection fails. * Unpaid or partially paid invoices with a completed [chargeback](/docs/payments/chargebacks). This option is off by default and applies only to that sequence. It also changes how its reminders wait for collection and catch up after a delay: * **Wait for automatic collection.** Hyperline defers reminders while a payment is pending, scheduled, or waiting to be processed, or while another automatic payment attempt remains possible. This includes a retry scheduled for later, even if no payment is currently pending. * **Continue at the latest due step.** Once the invoice is eligible, Hyperline sends the latest elapsed reminder on or after the due date. Hyperline skips earlier missed steps and does not repeat steps already sent. Hyperline sends at most one reminder per invoice per day. * **Keep pre-due reminders on their scheduled day.** Hyperline does not send a missed reminder from before the due date later. Hyperline checks eligibility again before sending. If payment collection has restarted or the invoice no longer qualifies, the reminder is skipped. Enabling this option can include invoices already in `error` or with a completed chargeback. It does not restart the sequence from its first email, change payment methods, or initiate a payment attempt. A sequence has reminders one, seven, and fourteen days after the due date. With **Include invoices with payment issues** enabled, automatic retries finish unsuccessfully on day nine. At the next daily check, Hyperline sends the day-seven step if the invoice is eligible and that step has not already been sent. It skips the missed day-one step. The day-fourteen step remains scheduled relative to the original due date. With the option off, Hyperline sends reminders only on each step's scheduled day. Hyperline does not send missed steps later. #### Other eligibility conditions The invoice must have an outstanding balance. Paid, canceled, draft, deleted, or refunded invoices are excluded, as are invoices with a pending or completed payment reconciliation. Enabling **Include invoices with payment issues** does not automatically include imported invoices. If an imported invoice is missing from reminders, contact the team through the in-app chat to check its eligibility. ### Emails 1. Click **New email**. 2. Set **Email trigger** to the number of days **Before due date**, **On due date**, or **After due date**. 3. Write the **Subject** and **Body**. 4. Use **Send test email** to preview the content at an email address of your choice. 5. Repeat for each step, then click **Save changes**. Each trigger is relative to the invoice due date, not the previous email. Use a different trigger day for each step. Hyperline attaches the invoice PDF to reminders. Recipients come from the customer's **Invoice emails** field; if none are set, Hyperline uses the customer's main **Email**. See [Invoice emails](/docs/invoices/emails) for recipient and sender configuration. When including failed payments and chargebacks, review the email wording so it also suits those situations. For example, ask the customer to settle the outstanding balance rather than assuming they forgot to make a bank transfer. ## When reminders are sent Hyperline checks reminder sequences daily at **6 AM UTC**. Hyperline queues emails from that check, so delivery is not guaranteed at exactly 6 AM. Timing is based on the invoice due date, regardless of the hour the invoice was issued. Creating or activating a sequence does not send a reminder immediately. At the next check, Hyperline evaluates the current audience, invoice eligibility, and schedule. For sequences with **Include invoices with payment issues** enabled, the latest-due-step behavior also applies when the sequence is activated after a reminder date has passed. ## Pause a sequence or exclude a customer To stop a sequence, open it and click **Actions > Pause**. Use **Actions > Activate** to resume it. Resuming follows the same schedule rules: exact-day reminders with the invoice option off, or the latest eligible due step with it on. Previously sent steps are not replayed. To exclude one customer from all reminder sequences: 1. Go to **Customers** and open the customer. 2. Click **Edit**. 3. Turn off **Send invoice emails reminders** and save. This customer setting controls reminder sequences separately from other invoice notifications. ## Track sent reminders Open the invoice's **History** to find reminder events. To inspect recipients, saved email content, delivery status, and delivery events, go to **Audit logs > Email activity**. See [Sent emails and delivery history](/docs/account/emails#preview-sent-emails-and-delivery-history). ## Troubleshoot a missing reminder Check the following before the next daily run: * **Sequence:** it is active, contains email steps, and has no broken audience filters, such as a deleted custom property. * **Audience:** the customer matches the intended sequence and has reminders enabled. A matching segment sequence may take priority over a custom audience. * **Invoice:** it has an outstanding balance and meets the conditions in [Invoices](#invoices). For an invoice in `error` or with a chargeback, enable **Include invoices with payment issues** on the sequence that actually matches the customer. * **Collection:** when that option is enabled, an in-progress payment or a remaining automatic attempt defers the reminder, including an attempt due later. * **Schedule and history:** a step is due and has not already been sent. Without the option, a missed date is skipped; with it, only the latest eligible elapsed step is considered. * **Recipients:** the customer has an invoice email address or a main email address. If these checks do not explain the missing reminder, contact the team through the in-app chat with the invoice and sequence details. ## Related guides * [Payment errors, retries, and fallback](/docs/payments/payment-errors) * [Chargebacks](/docs/payments/chargebacks) * [Customer segments](/docs/customers/segments) * [Email settings and delivery history](/docs/account/emails) # Tax management Source: https://docs.hyperline.co/docs/invoices/tax-management Apply the right VAT and sales tax rules on Hyperline invoices, with country-specific rates, reverse charge logic, and exemption handling. When invoicing customers, businesses must apply the correct tax scheme based on their location and the applicable laws. The two main types of taxes commonly seen on invoices are **Value-Added Tax (VAT)** and **Sales Tax**. ## How does VAT work VAT is a consumption tax applied at every stage of the supply chain where value is added, from production to the point of sale. The final consumer ultimately bears the tax. VAT is common in most countries worldwide, particularly in Europe and some parts of Asia and Africa. VAT rates vary by country and are often categorized into standard, reduced, and zero rates for different goods and services. ### In the EU First and foremost, ensure that you're registered with your country's tax authority and hold a valid VAT registration number, also known as an EU VAT Identification number. This number will be essential for conducting VAT-related activities. Next, determine whether your customers are businesses or consumers. Hyperline validates EU VAT numbers and uses the result when deciding whether reverse charge can apply. The chart below summarizes how Hyperline determines VAT for an EU-based invoicing entity. It assumes that automated tax collection is enabled. ```mermaid theme={null} flowchart TD A{"Is the customer marked
as tax exempt?"} A -- "Yes" --> B["VAT exempt"] A -- "No" --> C{"Is a manual VAT
rate set?"} C -- "Yes" --> D["Apply the manual VAT rate"] C -- "No" --> E{"Is the customer in
the EU VAT area?"} E -- "No" --> F["No EU VAT
Local tax rules may apply"] E -- "Yes" --> G{"Are the seller and customer
in the same VAT territory?"} G -- "Yes" --> H["Apply the seller-country VAT rate"] G -- "No" --> I{"Does the customer's VAT ID meet
your reverse-charge rules?"} I -- "Yes" --> J["Apply reverse charge
0% VAT"] I -- "No" --> K{"Is the customer typology
B2C (person)?"} K -- "No" --> H K -- "Yes" --> M{"Has this invoicing entity exceeded
€10,000 in eligible annual sales?"} M -- "No" --> H M -- "Yes" --> L["Apply the customer-country VAT rate"] classDef result fill:#FFF4D6,stroke:#E4B84B,color:#28251F; classDef exempt fill:#FCE8E6,stroke:#E39189,color:#28251F; class B,F exempt; class D,H,J,L result; ```
When issuing invoices, it is mandatory to include VAT, even if it is zero-rated. VAT returns must also be submitted on a regular basis, typically monthly, quarterly, or annually, depending on the specific requirements of each country. Be diligent in fulfilling these obligations to remain compliant. Once you are registered for VAT in another EU country, it's important to note that you should not charge VAT for both your own country and the customer's country. VAT should only be applied once, in accordance with the rules and regulations of the customer's location. Lastly, keep in mind that obtaining VAT registration in a new country can be a time-consuming process, typically taking around 6 weeks. This timeline can vary depending on the country where you are seeking registration. Patience and adherence to the necessary procedures will be key during this period. #### EU cross-border B2C threshold When you use Hyperline's automated tax engine, Hyperline automatically tracks the EU-wide €10,000 threshold used for eligible cross-border business-to-consumer (B2C) sales. Below this threshold, VAT is calculated using the rate of the invoicing entity's country. Once the threshold is exceeded, subsequent eligible invoices use the VAT rate of the customer's country. Hyperline tracks the threshold: * Separately for each invoicing entity * Per calendar year * Using amounts excluding tax from issued invoices in euros * Only when the customer's current typology is B2C (person) * Using invoices that do not include a tax ID Domestic sales do not change their applicable VAT rate when the threshold is exceeded. Cross-border B2B sales that qualify for reverse charge follow the [reverse charge rules](#eu-vat-and-tax-id-validation) instead. Your French invoicing entity sells to consumers in Spain. While its tracked annual amount is at or below €10,000, eligible invoices use the French VAT rate. After issued invoices bring the tracked amount above €10,000, subsequent eligible invoices use the Spanish VAT rate. The €10,000 threshold applies only to certain cross-border B2C supplies. See the [European Commission's cross-border VAT guidance](https://europa.eu/youreurope/business/taxation/vat/cross-border-vat/index_en.htm) and confirm your obligations with your tax adviser. ### Outside the EU If you're a business registered within an EU-based country, you don't charge VAT for customers that are based outside of the EU. Please take a look [at this page](https://uscib.org/value-added-tax-rates-vat-by-country/) to learn more about the different VAT rates globally. ## How does sales tax work Sales tax is a tax imposed on the sale of goods and services, collected only at the point of sale from the end consumer. It is primarily used in the United States and some parts of Canada. Rates are usually set by states or local governments and vary significantly across jurisdictions. ## Configure taxes in Hyperline In Hyperline, you manage tax settings per invoicing entity. This gives you flexibility in defining specific tax behavior depending on the legal entity responsible for issuing customer invoices. Hyperline automatically resolves the right tax scheme and applies the standard tax rate, the default rate of taxation applied to most goods and services. This is the general rate set by the government, which applies unless a specific good or service qualifies for a reduced rate, zero rate, or exemption. Two options are available regarding VAT collection: 1. **Automated tax collection**: Hyperline will automatically collect taxes based on your origin country and customer information (country, VAT number, tax ID, etc.). Hyperline then applies the correct VAT amount and rate on the issued invoices. 2. **Manual tax handling**: Hyperline allows manual tax handling where you are responsible for filing taxes by country. To use manual tax handling, go to **Settings** > **Taxes** for the relevant invoicing entity and turn off **Enable automated tax collection**, which is enabled by default. ## Tax calculation on invoices The taxes (rates and amounts) will appear on all invoices under the billed subtotal. When creating, editing, or duplicating invoices, you can manually set custom rates for each individual line. Tax is calculated on each invoice line item, then aggregated into the invoice totals. This means line-level rounding can affect the final tax total, especially when invoices contain several products, discounts, or mixed tax rates. If you need to review or adjust line-level taxes before the customer is charged, enable draft invoices or configure a grace period for usage-based invoices. ### Grace period for metered invoices For metered and usage-based subscriptions, the `grace_period` is the number of days an invoice stays open after the billing period ends. During this period, the invoice is not finalized or charged, so you can review usage, adjust line items, or correct taxes before payment collection starts. When the grace period ends, the invoice is finalized, assigned an invoice number, and moves to payment according to the customer's payment method and invoice settings. ## Customer tax settings You can customize the tax rate per customer if necessary. However, be careful: a manual tax rate set on a customer will not allow Hyperline to display any legal information associated with that rate in the invoice. You can add a custom invoice note for the customer to fix this. ### Customize tax rate per customer ### Taxability per customer You can mark each customer as **Taxable** or **Tax exempt** from the customer edit form. Use **Taxable** for the standard case where Hyperline should calculate taxes from your tax settings, customer location, tax ID, and product configuration. Use **Tax exempt** when a customer should not be charged tax, for example when you have collected and validated a tax exemption certificate outside Hyperline. Customer taxability is separate from a custom tax rate. Use taxability to decide whether tax applies at all, and custom tax rates to override the rate used for a taxable customer. ## Customer tax identifiers Company customers can have a primary **Tax ID**, such as an EU VAT number, and a **Local tax number** for country-specific invoicing or reporting requirements. The Tax ID is used for tax calculation, validation, and reverse charge rules. The local tax number is stored separately and does not receive a VIES validation status or make a customer eligible for reverse charge. To collect local tax numbers, navigate to **Settings** > **Taxes** for the relevant invoicing entity and enable **Enable local tax number**. The **Local tax number** field then appears when you create or edit a company customer and in customer billing forms on hosted pages. A German company can provide its EU VAT number as the **Tax ID** and its domestic tax number as the **Local tax number**. Hyperline uses the EU VAT number for VIES validation and reverse charge rules while retaining the domestic number for invoicing records. ## EU VAT and tax ID validation Hyperline automatically manages VAT in the EU. For B2B customers in another EU country, the reverse charge rate can apply when the customer has a tax ID on their profile. You can add the tax ID yourself from the customer page, or ask the customer to provide it from a portal, checkout, or quote signature flow. ### Tax ID validation When a customer tax ID is added or updated, Hyperline checks its format and, for EU VAT numbers, validates it through the EU VAT Information Exchange System (VIES). EU VAT numbers are then revalidated with VIES regularly, at least once a month, so the status can change if the VAT number is updated in the official registry. The validation status appears next to the customer's **Tax ID** on the customer page. | Status | Meaning | | - | - | | `valid` | The tax ID has been verified and is valid. | | `invalid` | The tax ID has been checked and failed validation, for example because it has the wrong format, is not found in VIES, or belongs to an inactive VAT registration. | | `mismatch` | The tax ID is valid, but it belongs to a different country than the customer's country. | | `unverified` | The tax ID has not been verified yet. | | `unsupported` | Hyperline does not support automated verification for this tax ID type yet. | Use the **Customers** list to filter customers by tax ID status. This helps you find records with `invalid`, `mismatch`, `unverified`, or `unsupported` tax IDs. You can then correct the tax ID, ask the customer to update their billing details, or decide the right follow-up action. For EU VAT numbers, Hyperline stores the VIES consultation number on the customer and on invoices that rely on that validation. This gives your finance team a reference for later checks. Tax ID validation helps you identify risky billing details, but it does not replace review by your finance, tax, or accounting team. VAT databases are not always up to date, and an otherwise valid VAT number may still require additional checks for your billing context. ### Customize the reverse-charge statement When reverse charge applies, Hyperline prints a legal statement on the invoice. By default, Hyperline uses a standard wording localized to the invoice language and adapted to the invoicing entity's country. For example, French entities reference art. 283 of the French General Tax Code. You can replace this default with your own wording per invoicing entity: 1. Go to **Settings** > **Invoicing entities**, select the invoicing entity, then open **Invoicing**. 2. In the **Invoices** tab, fill in the **Reverse-charge legal statement** field. 3. Click the globe icon to provide a different statement for each invoice language. The field's placeholder shows the default statement used for the selected language. 4. Click **Save changes**. When generating an invoice, Hyperline prints the statement matching the invoice language. If the field is left empty for a language, Hyperline falls back to the default localized wording. ## Tax enforcement options You configure tax enforcement per invoicing entity. This lets each legal entity decide how strictly Hyperline should require and validate tax IDs before applying tax rules. To configure tax enforcement, navigate to **Settings** > **Taxes** for the relevant invoicing entity. ### Enable local tax number Enable **Enable local tax number** when company customers need to provide a country-specific tax number in addition to, or instead of, their primary Tax ID. This setting makes the **Local tax number** field available on customer records and hosted billing forms for the selected invoicing entity. The field is optional unless **Require customer tax identifier** is also enabled. Hyperline stores the local tax number on the customer's billing details and captures it on generated invoices. ### Require customer tax identifier Enable **Require customer tax identifier** when all company customers billed by an invoicing entity must provide a tax identifier before invoices, quotes, or hosted-page billing details can be completed. * When **Enable local tax number** is disabled, the customer must provide a Tax ID. * When **Enable local tax number** is enabled, the customer can provide either a Tax ID or a local tax number. This setting checks that an identifier is present; it does not require the Tax ID to be externally validated. A local tax number does not replace a valid Tax ID for reverse charge rules. ### Enforce a valid tax ID for reverse charge By default, Hyperline applies the reverse charge rate as soon as a tax ID is provided on the customer's profile, without waiting for external validation. Enable **Require valid tax ID for reverse charge** when reverse charge should apply only after the customer's tax ID has the `valid` status. If the tax ID is missing, `invalid`, `mismatch`, `unverified`, or `unsupported`, Hyperline applies the standard tax rate for the customer's country instead. This setting is useful when your tax policy requires VIES validation before applying a 0% reverse charge rate. This setting is disabled by default. If VIES validation is temporarily unavailable, a tax ID may remain `unverified`; with this setting enabled, Hyperline will not apply reverse charge until validation succeeds. ## Tax mappings Tax mappings associate the tax rates used by Hyperline with the corresponding codes in your accounting software. You configure them separately for each invoicing entity. The **Tax mappings** list brings together: * Country-specific rates, including standard and reverse charge rates * Reusable custom rates, identified by the `Custom` label * The accounting code associated with each rate The **Applies to** column shows the country of each mapping and, for standard mappings, the sales scope underneath. You can search the list by mapping name, country, rate, or code. Use the action menu on a row to manage an existing mapping. ### Create a tax mapping Go to **Settings** > **Taxes** for the relevant invoicing entity. Enter the mapping details and the code used by your accounting software, then save the mapping. When you send an invoice to connected accounting software, Hyperline associates the applicable tax mapping with its invoice lines. You can also assign custom tax mappings to products in your catalog for each invoicing entity. Use them when a product requires a reusable rate that differs from the country-specific rates resolved by the tax engine. ### Sales scope When you create a standard tax mapping, the **Scope** selector controls which sales the mapping applies to. This lets you map the same country and rate class to different accounting codes depending on where the sale goes. | Scope | Applies to | | - | - | | **All sales** | Every sale matching the mapping's country and rate class | | **Domestic sales** | Sales where the customer is in the invoicing entity's country | | **Intra-EU sales** | Cross-border sales within the EU VAT area | | **International sales** | Sales outside the invoicing entity's country and the EU VAT area | The scope defaults to **All sales**. Keep the default when a single accounting code covers all sales for that country and rate class. Create several mappings with different scopes when your accounting software uses separate tax codes for domestic, intra-EU, and international sales. A few things to keep in mind: * You set the scope when you create the mapping, and you cannot change it when editing it. To use a different scope, create a new mapping. * The scope is available on standard tax mappings only. Custom tax mappings do not have a scope. * The **Tax mappings** list shows each mapping's scope in the **Applies to** column, below the country. The scope is also exposed as the `scope` field on the [tax rate API endpoints](/api-reference/endpoints/taxes/list-tax-rates). ### Regional shortcuts When you create a standard tax mapping, the country picker exposes three regional shortcuts below the country list. Each shortcut is marked with a globe icon and targets a group of countries instead of a single one. | Shortcut | Covers | Available rate class | | - | - | - | | **EU VAT area** | Customers in EU VAT territories | Reverse charge (0%) | | **Outside the EU VAT area** | Customers outside the EU VAT area | Exempt (0%) | | **Other countries** | Any country not matched by a more specific mapping | Exempt (0%) | Use a regional shortcut when the same accounting code should apply to every country in that group. Two common cases: * **EU reverse charge.** Create a standard mapping on **EU VAT area** with the **Reverse charge** rate class. This associates a single accounting code with cross-border B2B sales inside the EU that qualify for reverse charge. * **Non-EU exempt.** Create a standard mapping on **Outside the EU VAT area** with the **Exempt** rate class. This associates a single accounting code with sales to customers outside the EU VAT area. Regional shortcuts differ from country-level mappings in two ways: * They target a group of countries, so you don't need to create one mapping per country to cover a region. * They are opt-in on standard tax mappings only. They do not appear when you configure the eligible countries of a custom tax mapping, which still accepts individual countries. # Invoice payment term Source: https://docs.hyperline.co/docs/invoices/term Set invoice payment terms in Hyperline to define how long customers have to pay and when invoices are flagged as late, with configurable defaults. When you set a payment term, Hyperline marks invoices as **late** once the payment term has passed. Choose a number of days that fits your industry's standard or your company preferences. The payment term starts to run from the day the invoice is emitted to be paid. A default payment term of **30 days** is configured in your settings (**Settings** > **Invoicing** page). You can change it to your preferred value. Hyperline applies this payment term to all your customers. #### Customization per customer In the **Advanced** section, you can enter the custom payment term negotiated with your customer. You can update this setting afterward using the **Edit customer** action. The change applies to every invoice created afterward. ## Grace period For invoices with usage-based products, Hyperline uses a grace period, defined as a number of days, to **leave invoices open** before sending them for payment. This period allows you to review the invoices before they are finalized. At the end of this period, Hyperline automatically sends invoices for payment. The default duration is 3 days, but you can configure it on the **Settings** > **Invoicing** page. #### Behavior during the period During this period, Hyperline takes newly ingested events for the invoice billing period into account and regularly updates invoices, so they have the latest accurate usage data. Invoices in grace period don't have a unique number (not part of the sequential numbering). Hyperline generates this number when the invoice is finalized/ready to be paid. When the invoice leaves the grace period and is ready to be paid, Hyperline sends an `invoice.ready` webhook message. For more details about webhooks, see the [webhooks page](../../developers/webhooks). ## Payment initiation delay The payment initiation delay is different from the payment term. The payment term defines when an invoice becomes late. The payment initiation delay defines when Hyperline starts collecting payment on invoices with an automated payment method, such as card or direct debit. When you set a payment initiation delay, Hyperline doesn't charge the invoice when it's ready to be paid. Hyperline schedules a [transaction](../payments/scheduled-transactions) for the amount due instead, and processes it once the delay has passed. You can configure the default delay in **Settings** > **Invoicing**, under **Payment initiation delay**. To override it for a specific customer, set a **Custom payment initiation delay** using the **Edit customer** action. The payment initiation delay also applies to invoices generated by a checkout. See [Checkout with a payment initiation delay](../subscriptions/checkout-page#checkout-with-a-payment-initiation-delay). # Understand payment allocations Source: https://docs.hyperline.co/docs/payments/allocations Learn how Hyperline allocates payments, refunds, chargebacks, credit notes, and wallet funds to invoices, and how to reassign unallocated amounts. An allocation tells Hyperline how much of a financial movement applies to a specific invoice or credit note. The financial movement and its allocation are separate: * A **transaction** records money collected or returned, such as a card payment, bank transfer, refund, or chargeback. * An **allocation** assigns all or part of that transaction to a document. * An **unallocated amount** is the part of a transaction that has not yet been assigned to any document. Creating or removing an allocation does not move money. It changes how an existing movement is applied to invoices and credit notes. ```mermaid theme={null} flowchart LR T["Transaction
€350"] --> A1["Allocation
€200"] T --> A2["Allocation
€100"] T --> U["Unallocated
€50"] A1 --> I1["Invoice A"] A2 --> I2["Invoice B"] ``` ## Transactions, unallocated funds, and wallets An unallocated transaction and a wallet balance can both look like available customer funds, but they serve different purposes. | Concept | What it represents | How it is used | | - | - | - | | **Transaction** | A specific movement of money that has already happened or is being processed | Provides the source amount that can be assigned | | **Unallocated amount** | The part of a transaction that is not assigned to an invoice, credit note, or wallet | Waits for a manual matching decision | | **Wallet balance** | Funds intentionally made available on the customer's account | Can be used automatically or manually on future invoices | | **Wallet consumption** | A debit from the wallet used to pay an invoice | Reduces the wallet balance and contributes to the invoice payment | A transaction is evidence that money moved. It is not itself a customer balance. Its amount can be allocated directly to one or more invoices, added to the customer's wallet, or left unallocated while you decide how to match it. ```mermaid theme={null} flowchart LR T["Transaction received"] -->|"Allocate directly"| I["Invoice"] T -->|"Add to wallet"| W["Wallet balance"] W -->|"Use wallet funds"| I2["Current or future invoice"] T -->|"No decision yet"| U["Unallocated amount"] ``` The same amount cannot be available in more than one place. An amount is either unallocated, allocated directly to a document, or added to the wallet. This prevents the same funds from being used twice. Unallocated transactions are useful for payments that still need to be reviewed or matched, such as an imported bank transfer. Wallet funds have already been assigned to the customer balance and can therefore participate in automatic invoice collection. ## Why allocations matter Allocations let Hyperline represent payment situations that are more complex than one payment for one invoice. You can use them when: * One bank transfer pays several invoices * One invoice is paid using several transactions or payment sources * A transaction is only partially applied and keeps an unallocated remainder * A payment is matched to an invoice after it was received * A credit note is partly applied, partly refunded, and partly added to a wallet * A refund or chargeback must remain traceable to its original payment * Wallet funds from several top-ups are used to pay one invoice ## How an allocation affects an invoice An allocation determines which invoice a transaction contributes to. The transaction status determines when that contribution becomes effective. For example, a pending payment can already be assigned to an invoice so that the same invoice amount is not collected twice. The invoice is considered paid only according to the payment and invoice status rules that apply to that movement. Hyperline limits allocations to the amounts that can actually be assigned: * The sum allocated cannot exceed the transaction amount * An invoice cannot receive more than its remaining payable amount * The transaction and invoice must belong to the same customer, currency, and invoicing entity * A standard payment cannot be used to settle a credit note * Only eligible, active documents can receive new allocations If you try to assign more than an invoice can receive, Hyperline allocates the maximum valid amount and leaves the rest of the transaction unallocated. You receive a €300 bank transfer and select an invoice with €200 left to pay. Hyperline allocates €200 to the invoice and keeps €100 unallocated. You can later allocate that €100 to another eligible invoice for the same customer. ## One transaction can pay several invoices A transaction can have several active allocations. Each allocation has its own amount. A customer sends one €500 bank transfer for two invoices. You allocate €300 to the first invoice and €200 to the second. Both invoices refer to the same transaction, while each displays only the amount assigned to it. The reverse is also possible: one invoice can combine several payment sources, such as a wallet balance, a bank transfer, and a card payment. ## Add a payment to an invoice Open a finalized invoice and select **Actions** > **Add payment**. The action is available while the invoice still has an amount left to pay, including invoices in the **Late** or **Error** status. Depending on the funds available for the customer, Hyperline offers up to three options: 1. **Use wallet balance** uses funds already available in the customer's wallet. 2. **Use existing transaction** allocates all or part of a compatible transaction that still has an unallocated amount. 3. **Record offline payment** records money received outside Hyperline and allocates it to the invoice. Hyperline selects the first available option automatically. Enter the amount to apply and confirm with **Add payment**. Hyperline never applies more than the amount left to pay. Any unused part of an existing transaction remains unallocated. ## Add a refund to a credit note On a credit note, the equivalent action is **Actions** > **Add refund**. It settles the credit note's remaining balance instead of collecting a payment. Depending on the customer's situation, Hyperline offers up to three options: 1. **Top up wallet** adds the refund amount to the customer's wallet and links it to the credit note. Available when the customer has a wallet in the credit note's currency. 2. **Use existing refund** allocates all or part of a refund transaction that still has an unallocated amount. 3. **Create new refund** records a refund made outside Hyperline and allocates it to the credit note. The amount defaults to the credit note's remaining balance and cannot exceed it. See [Refund an open credit note](/docs/invoices/refunds#refund-an-open-credit-note) for the full workflow. ## Allocate a payment after receiving it Some transactions exist before they are matched to an invoice. This is common for bank transfers imported through Open Banking or payments recorded manually. Until the transaction is allocated: * The money movement remains recorded in Hyperline * Its unallocated amount is available for a future match * It does not settle an invoice by itself Once you allocate it, Hyperline recalculates the affected invoice balances and statuses. ### Record a transaction received outside Hyperline Use **Record transaction** when the money moved outside Hyperline and no transaction exists yet. Open the customer's **Transactions** page, click **Record transaction**, then select the type of movement: * **Payment** records money received from the customer. Enter the payment date, payment method, amount, and an optional reference. When wallets are enabled, you can turn on **Add payment funds to wallet**. This makes the funds available in the customer's wallet for future payments instead of leaving them unallocated. * **Refund** records money returned to the customer. You can optionally link the refund to the original payment. The transaction selector shows the amount still available on each eligible payment. * **Chargeback** records a dispute handled outside Hyperline. You must link the chargeback to the original payment. For payments and refunds, you can record the movement as either: * **Bank transfer**, optionally associated with one of your bank accounts * **External payment method**, for another payment handled outside Hyperline You cannot manually record a payment against a stored card or direct debit payment method. Those methods require a real charge processed by the connected payment provider. If a card payment was collected outside Hyperline, record it as an **External payment method** instead. An existing card or direct debit transaction can still be allocated after its provider has processed it. In that case, you are assigning an existing money movement rather than recording a new offline one. A recorded payment that is not sent to the wallet starts fully unallocated. Its amount stays available until you allocate it to an invoice with **Add payment** or add it to the wallet. ### Delete an offline transaction If you recorded an offline transaction by mistake, you can delete it. Deleting removes the transaction entirely, unlike unallocating, which only detaches it from a document. You can delete a transaction only when all of the following are true: * It was recorded as a **bank transfer** or **external payment method**. Transactions processed by a connected payment provider cannot be deleted. * It has no active allocations. Unallocate it first if needed. * Its funds were not added to a wallet. * It is not a chargeback. To delete an eligible transaction, open its details and click the red **Delete transaction** button at the bottom of the panel. Confirm in the modal that opens. Hyperline then deletes the transaction and recalculates the customer's balances. Deleting a transaction cannot be undone. To correct a wrong amount or date instead, delete the transaction and record it again. ## Remove or change an allocation Removing an allocation separates the transaction from the invoice, but it does not delete or refund the transaction. After an allocation is removed: * The amount becomes available to allocate again * The previous invoice balance and status are recalculated * The transaction remains visible in Hyperline * The previous allocation remains in the allocation history To move a payment from one invoice to another, remove the current allocation and create the new one. Hyperline keeps both the past relationship and the new active relationship. To remove an allocation, open the invoice, find the payment in **Transactions**, open its action menu, and select **Unallocate**. For a wallet payment, use **Reverse wallet payment** instead because the wallet debit must be cancelled and returned to the wallet balance. Unallocating a settled payment can make a previously paid invoice payable again. It does not reverse the external payment. ## Current allocations and allocation history Hyperline distinguishes between current allocations and the transaction's history: | View | Meaning | Effect on balances | | - | - | - | | **Current allocations** | The transaction amounts currently assigned to documents | Included in current invoice calculations | | **History** | The timeline of everything that happened to the transaction, including past allocation changes | Kept for traceability, with no current balance effect | The transaction details show the documents currently receiving the transaction. The **History** section below them shows a timeline of the transaction's lifecycle events: * **Transaction created**, **Transaction updated**, **Transaction processed**, and **Transaction deleted** record changes to the transaction itself. * **Allocation updated** records each allocation change, with the amount allocated to or unallocated from each invoice and a link to that invoice. Each event shows when it happened and, where available, who or what triggered it. This lets you reconstruct where a transaction's amount was applied before, even after an allocation was removed or replaced. Voiding or deleting a document can end its active allocations. Hyperline keeps these events in the history so that you can still understand how the transaction was used over time. ## Refunds Hyperline supports two refund situations with different effects. ### Refund a payment directly A direct refund returns money from the original payment without cancelling the invoice amount. The refund remains linked to the original payment and reverses the corresponding payment allocations. The invoice can therefore become payable again. Use this when the customer should receive the money back but still owes the invoice amount. ### Refund through a credit note A credit note reduces or cancels the amount the customer owes. When the credit note is refunded, the refund transaction settles the credit note rather than the original invoice. The complete relationship remains visible: * The credit note is linked to the invoice it reduces * The refund is linked to the original payment * The refund is assigned to the credit note it settles This separation prevents the invoice amount from being reduced twice. See [Credit notes & refunds](/docs/invoices/refunds) for the workflows available in Hyperline. ## Credit note allocations A credit note has its own available amount. You can use that amount in several ways: * Apply it to one or more invoices * Refund it through the original payment method * Record a refund made outside Hyperline * Add it to the customer's wallet for future use * Keep the remaining amount available Hyperline tracks the total used across all these destinations. The same part of a credit note cannot be both applied to an invoice and refunded or credited to a wallet. A €300 credit note can be split into €100 applied to an invoice, €120 refunded to the customer, and €50 added to their wallet. The remaining €30 stays available. Credit notes can only be applied to compatible invoices for the same customer, currency, and invoicing entity. Hyperline limits each application to both the credit note's available amount and the invoice's remaining amount due. The credit note detail page separates these relationships: * **Reference invoice** shows the invoice the credit note was created from. * **Applied invoices** appears when the credit note's amount is allocated to other invoices. Each entry links to the invoice and shows the amount allocated to it. ## Chargebacks A chargeback is a separate transaction linked to the disputed payment. It is allocated only to the part of the payment that still contributes to an invoice. If part of the payment has already been refunded, Hyperline does not apply a chargeback to that same part again. This avoids reducing the invoice balance twice. A €100 payment is fully refunded, then the provider reports a €100 chargeback. The chargeback remains linked to the original payment and appears in its transaction history, but it has no current invoice allocation. The refund has already removed the full payment effect from the invoice. For this reason, a refund or chargeback can appear in an invoice's transaction history even when it has no active allocation to that invoice. Its relationship comes from the original payment, while allocations continue to represent the current financial effect. ```mermaid theme={null} flowchart LR P["Original payment"] -->|"Current allocation"| I["Invoice"] P -->|"Related movement"| R["Refund"] P -->|"Related movement"| C["Chargeback"] R -. "Reverses the payment effect" .-> I C -. "Applies only to the remaining effect" .-> I ``` See [Chargebacks](/docs/payments/chargebacks) for dispute-specific behavior. ## Wallet allocations A wallet keeps both a balance and the origin of its funds. Wallet credits can come from paid top-ups, offline payments, free funds, or credit notes. When adding paid funds to a wallet, you can use the unallocated amount of an existing transaction or record a new offline transaction. Moving an existing amount to the wallet removes it from that transaction's unallocated amount. A €300 bank transfer is used to pay €100 of an invoice directly. You can add the remaining €200 to the wallet. The transaction then has a €100 invoice allocation and a €200 wallet destination, with no unallocated remainder. When wallet funds pay an invoice, Hyperline uses the oldest available eligible funds first. This is a first-in, first-out allocation. A wallet contains a first top-up of €150 and a second top-up of €200. A €250 invoice payment consumes the remaining €150 from the first top-up and €100 from the second. The wallet keeps €100 from the second top-up. ```mermaid theme={null} flowchart LR F1["First top-up
€150"] -->|"€150"| C["Wallet consumption
€250"] F2["Second top-up
€200"] -->|"€100"| C F2 -->|"€100"| R["Remaining wallet funds"] ``` This history lets you identify which top-up funded each wallet consumption, including when one consumption uses several top-ups. If a wallet credit is reverted, Hyperline reallocates affected consumptions to other available funds where possible. Removing a direct transaction allocation and reversing a wallet payment are different operations: * **Unallocate** removes the relationship between a transaction and an invoice. The amount becomes unallocated on the same transaction. * **Reverse wallet payment** cancels the wallet consumption and returns the amount to the wallet balance. It does not create an unallocated transaction. Both operations recalculate the affected invoice, which can make a previously paid invoice payable again. See [Manage wallet balance](/docs/wallets/balance) for wallet top-up and consumption workflows. ## Accounting and reporting Current allocations are the source used to understand which documents a transaction settles. Hyperline uses them for invoice calculations, payment reporting, and supported accounting synchronization flows. Past allocation changes remain visible in the transaction's history for audit purposes but no longer affect current balances. Related refunds and chargebacks can still appear with the original invoice even when they have no current allocation. This keeps the full money-movement history understandable without counting an amount twice. ## How to read transaction relationships Use the following questions when investigating a payment: 1. **What money moved?** Review the payment, refund, or chargeback transaction. 2. **Where is it currently applied?** Review its current allocations and amounts. 3. **Was it applied somewhere else before?** Review the allocation changes in its history. 4. **Is it an adjustment?** Follow the link to its original payment. 5. **Did a credit note or wallet participate?** Review the related credit note applications or wallet funding sources. Do not interpret a missing active allocation as a missing transaction. A transaction can be unallocated, or it can be a refund or chargeback whose invoice effect has already been represented elsewhere. ## Related documentation * [Credit notes & refunds](/docs/invoices/refunds) * [Chargebacks](/docs/payments/chargebacks) * [Manage wallet balance](/docs/wallets/balance) * [How the customer balance is calculated](/docs/customers/balance) # Payment orchestration Source: https://docs.hyperline.co/docs/payments/orchestration Connect Stripe, Adyen, GoCardless, and other PSPs in one click. Hyperline orchestrates payment processing, customer sync, and reconciliation. Hyperline natively supports major Payment Service Providers (PSPs). This means that using these services won't require any technical work from you. Simply connect your account in one click and let Hyperline orchestrate it without extra work on your side. ## Orchestration Once connected, Hyperline automatically creates or updates customers and their associated information on the relevant payment providers as needed. Payment method collection forms, such as credit card inputs or Direct Debit mandates, are directly embedded within Hyperline flows, hosted pages, and frontend components. This requires no additional technical effort on your part. Payments are automatically triggered using the customer's payment method when appropriate. Hyperline natively manages all related flows, such as retries, refunds, and chargebacks, so you don't need to handle them manually. Hyperline uses payment allocations to determine how much of each transaction applies to each invoice. This supports partial payments, one transaction paying several invoices, and transactions matched after they are received. See [Understand payment allocations](/docs/payments/allocations) for the complete model. When a payment provider reports a dispute, Hyperline records the chargeback as its own transaction on the invoice, linked to the original payment. Hyperline then recalculates the invoice's paid amount, its status, and the availability of the **Add payment** action. See [Chargebacks](/docs/payments/chargebacks) to understand how disputes affect payments and invoice balances. By using Hyperline, you eliminate the technical complexity of integrating with a payment provider yourself. Hyperline abstracts that layer for you. As a bonus, switching between payment providers becomes seamless, since your application is no longer tightly coupled to any specific one. ## Import Hyperline allows you to connect your existing payment provider account and seamlessly migrate to our platform. Hyperline provides built-in mechanisms to import your customers and their associated payment methods, so you can get started without asking your customers to re-enter their payment details. If you're interested in onboarding with an existing setup, please contact our support team. We'll guide you through the process. ## Multi-providers Hyperline lets you connect multiple payment providers at the same time, giving you the flexibility to distribute payment method usage across providers based on cost, geography, or preferred features. For example, you can route card payments through Stripe while using Mollie for SEPA Direct Debit. This lets you take advantage of the best rates or capabilities each provider offers. You can also connect multiple accounts from the same provider, enabling more granular control over your payment routing strategy. # Handling payment errors Source: https://docs.hyperline.co/docs/payments/payment-errors Diagnose and resolve failed Hyperline payments: understand decline reasons, retry logic, and how to recover unpaid invoices for customers. ## Payments in Hyperline In most cases, Hyperline manages payment collection and reconciliation for you. But sometimes, payments can fail for a variety of reasons, resulting in unpaid invoices. When an invoice is issued and ready to be paid, Hyperline will attempt to charge the active payment method of the customer by initiating a payment. This is the basic use case for credit cards and Direct Debit. The customer should have previously added the payment method through the checkout or portal page. Note that if the customer pays by bank transfer, Hyperline sends the invoice to be paid by email. You then need to reconcile the payment manually in Hyperline (learn how to proceed on this page). If you connected a PSP, no action is required on your part. ## Errors and retry In certain situations, payment can fail (payment method expired, payment declined, processing issue on the bank side, etc.). For retryable failures, Hyperline uses the following default retry schedule: * 2 hours after the first attempt * 12 hours after the second attempt * 24 hours after the third attempt For each attempt, Hyperline creates a new transaction for the invoice. If payment fails and no automatic retries or eligible fallback methods remain, or the failure requires manual action, Hyperline marks the invoice as `error`. Retryable errors include: * **Insufficient funds**: The payment method doesn't have enough funds to complete the transaction * **Declined payments**: The card issuer or bank declined the payment. Reasons include cards reported as lost or stolen, reaching the limit available on the method, payment method on a known block list, security violations, banking service unavailability, etc. Hyperline doesn't automatically retry expired or invalid payment methods. You can enable [payment method fallback](#try-other-saved-payment-methods) to try another eligible saved method. Otherwise, your customer needs to update their payment details. When a customer has multiple invoices in error and adds an automated payment method (credit card, direct debit), Hyperline immediately charges all previous invoices. This state corresponds to the `error` status on the invoice API, and to the `invoice.errored` webhook message. ### Custom payment retry You can customize the retry schedule in **Settings > Payments > Retries**. You can add or remove attempts and adjust the delay between them. Disable **Enable payment retries** to stop repeated attempts on the same payment method. To handle failed payments entirely manually, also leave **Try other saved payment methods** disabled. ### Try other saved payment methods You can let Hyperline switch an unpaid invoice to another saved payment method when retries are exhausted or Hyperline can't retry the current method. This option is disabled by default. 1. Go to **Settings > Payments > Retries**. 2. Enable **Try other saved payment methods**. 3. Click **Save changes**. After a failed payment, Hyperline selects an eligible, active saved method for the same customer, such as another card or direct debit mandate. The customer's payment settings must allow the method, and the method must support the invoice currency. Hyperline prefers the customer's default method if eligible, then the oldest saved method, and skips methods already used on that invoice. The switch updates the invoice's payment method without changing the customer's default. Automatic collection resumes with a fresh attempt count and your configured retry schedule. For example, if retries on one card are exhausted, Hyperline can switch to a second saved card and start its attempts from the beginning. Fallback also works when **Enable payment retries** is disabled: after a failure, Hyperline can try another eligible saved method without retrying the same method. Hyperline does not switch methods while a payment is pending, scheduled, or processing. Cancelled payments, suspected fraud, and failures requiring customer authentication do not trigger fallback. Hyperline also excludes imported invoices. Enabling the option does not automatically restart collection for invoices already in `error`. To track a switch, open the invoice's history and look for **Payment method changed automatically**. The entry shows the previous and new payment methods and when the change happened. ## Subscription error Additionally, if the invoice is related to a running subscription, Hyperline switches the subscription to an "Error" state. You can disable this behavior in **Settings > Subscriptions**, letting subscriptions remain active even if some invoices failed to be paid. If the subscription invoice is flagged as errored, Hyperline considers the related subscription **inactive** (as the customer failed to pay you). This means that Hyperline won't invoice the customer in the future or collect payment. Invoices in `Open` state will stay in this state for as long as the subscription is paused. **This behaves as a paused subscription**. In this case, you can choose to **manually re-activate the subscription** (the invoice will remain unpaid) or **fully cancel it**. This state corresponds to the `errored` status on the subscription API, and to the `subscription.errored` webhook message. You can use this state to switch off the access to your product or move your customer to a free product access. ## Manual retry If you wish to manually retry the payment of an invoice with a failed transaction, click **Charge invoice** in the invoice actions dropdown. The charge form lets you adjust the collection before confirming: * **Payment method**: Hyperline preselects the payment method attached to the invoice, or the customer's default method. You can select any other payment method saved for the customer. * **Amount**: Hyperline prefills the amount left to pay. You can lower it to collect a partial amount. The amount cannot exceed the amount left to pay. Click **Charge** to start the payment. The result appears in the invoice transactions table. If the new payment is successful, the invoice is paid. The subscription automatically switches back to the live state if the customer is still in the subscription period. This will correspond to an `active` status on the subscription API, and to a `subscription.activated` webhook message. ## Customer notification If your customer can resolve the problem themselves, Hyperline emails them a link to their dedicated portal page, where they can update their payment details. For example, their card expired or was declined and needs to be replaced, or they have insufficient funds. ## Error types You can retrieve on the invoice the related transactions with the following `error_type` if the status is `failed`: * `authentication_required`: The card was declined as the transaction requires authentication (e.g. 3-D Secure). The customer should go to their portal page and authenticate their card. If the error happened on an already authenticated transaction, the customer needs to contact their card issuer for more information. * `payment_method_authorization_error`: A transaction authorization cannot be created for a variety of reasons such as the card issuer couldn't be reached, or the card requires a PIN. * `payment_method_declined`: The payment method was declined. Common reasons include a card reported as lost or stolen, insufficient funds, reaching the method's available limit, or a payment method on a known block list. * `payment_method_expired`: The payment method is expired. The customer should go to their portal page and change their payment method. * `payment_method_invalid`: The payment method is invalid in most cases because of incorrect details (card/account number, CVC, expiration date, postal code). * `payment_method_not_supported`: The payment method doesn't support this type of purchase (e.g. currency, online payment). * `declined`: The payment was declined for a variety of reasons such as security violation, banking service not available, transaction not allowed, etc. * `fraud`: The payment provider suspected the transaction was fraudulent and blocked it. Don't report more detailed information to your customer, and check on your provider account. * `processing_error`: The issuer couldn't process the payment for an unknown reason. * `provider_error`: An error occurred when contacting the payment provider to initiate the transaction. * `unknown`: A generic error happened on the payment provider side. ### Get notified of an errored invoice/subscription for a customer If you want to get notified when one of the invoices for your customer enters an error state because of a failed payment, you can implement multiple strategies. You can set up a handler on the `invoice.errored` or `subscription.errored` message. See more details on using the [webhooks page](../../developers/webhooks). You can also **leverage a no-code solution** with our native [Zapier app](../../integrations/zapier) to connect the tool of your choice and trigger internal action on your side. For example, you can notify a Slack channel, change state in one of your internal tools, email a specific team, etc. # Payment methods Source: https://docs.hyperline.co/docs/payments/payment-methods Browse Hyperline-supported payment methods: credit cards, SEPA and ACH direct debit, bank transfers, Apple Pay, Google Pay, and more by country. Hyperline supports out of the box a variety of payment methods, giving you the flexibility to propose different options to your customers. The available payment methods on your account mainly depend on your country of incorporation and your connected Payment Service Provider (PSP). * **Credit & debit cards**: Visa, Mastercard and American Express * **Direct Debit**: * **SEPA** Direct Debit for customers in the Single Euro Payments Area * **ACH** Direct Debit (for customers with a bank account in the US & in USD) * **Bacs** Direct Debit (for customers with a bank account in the UK & in Pounds) * **Bank transfers**: direct bank transfers from your customers to your bank account * **Apple Pay** and **Google Pay** In **Settings** > **Payment**, you can connect the PSP you want to use and select the payment methods you want to enable on your account. If you use invoicing entities, you can configure the bank account shown on bank transfer invoices for each entity. You can use one account for all invoices or [assign bank accounts or bank transfer providers by invoice currency, customer country, or customer segment](../account/invoicing-entities#configure-bank-accounts-for-bank-transfers). ## Payment service provider Hyperline natively supports major Payment Service Providers (PSPs). This means that using these services won't require any technical work from you, and Hyperline fully orchestrates your PSP account without extra work on your side. | PSP | Supported payment methods | | - | - | | Stripe | Card, SEPA Direct Debit, ACH Direct Debit, Apple Pay, Google Pay | | Mollie | Card, SEPA Direct Debit, SEPA Transfer | | GoCardless | SEPA Direct Debit, Bacs Direct Debit, ACH Direct Debit | | Airwallex | Card, SEPA Direct Debit, Bacs Direct Debit, ACH Direct Debit | | Adyen | Card, SEPA Direct Debit, Bacs Direct Debit, ACH Direct Debit | ### Configure Apple Pay and Google Pay To use Apple Pay and Google Pay, you must first enable them and register specific web domains in your payment service provider (PSP) account. These payment methods require domain verification in order to function properly when embedded in web pages. To complete this step, register the domain `hyperline.co` in your PSP account. If you've configured a custom domain on Hyperline for your hosted pages, you must register that domain as well. More details in the [Stripe documentation](https://stripe.com/docs/apple-pay/web#register-your-domain). ## Customer payment methods Hyperline gives you **fine-grained control over which payment methods are available to each customer**. This allows you to tailor the payment experience and **restrict certain methods** based on customer-specific needs or preferences. Hyperline displays the enabled payment methods to the customer on their [**portal page**](../customers/portal) or when using [**embedded components**](../../developers/react-components). You can configure this in two ways: * Via the **Settings** modal under the **Payment Methods** section on the customer's page. * While assigning a subscription to a customer, by selecting the allowed payment methods for the customer. ### Inherit, override, or disable a method By default, a customer's payment methods follow the defaults configured on their [invoicing entity](../account/invoicing-entities#payment-methods). For each payment method, you can select one of three states: * **Use default settings**: the method inherits the invoicing entity configuration. The option displays the entity's current default (payment provider or, for bank transfers, bank account) so you can see exactly what applies. When you update the entity settings later, the change automatically flows through to every customer using this option. * **Override**: select a specific payment provider (or bank account for bank transfers) for this customer. The customer keeps this value even if the entity defaults change. * **Disabled**: the method is not offered to this customer, regardless of the entity configuration. Use overrides when a specific customer needs a different provider or bank account than the rest of the entity. Keep **Use default settings** everywhere else so entity-level changes propagate without per-customer maintenance. You can optionally configure a **default payment method** for each customer: a saved payment method, **bank transfer**, or **Outside of Hyperline**. If no default is set, Hyperline will automatically use the **first payment method** provided by the customer. You can enable [payment method fallback](./payment-errors#try-other-saved-payment-methods) to try another saved method after a failed payment. This changes the invoice's payment method without changing the customer's default. ## Manage payments outside of Hyperline If you prefer not to use Hyperline's built-in payment capabilities, you can manage payments **entirely outside of the system**. This is particularly useful if you already operate a complex banking infrastructure or act as your own payment processor. In this case, there's no need to connect a payment service provider (PSP). You can configure the customer's payment method as **"Outside of Hyperline"**, which: * Disables all payment-related logic in billing flows * Removes payment method sections from the **hosted pages** (checkout, quote, invoice) and **customer portal** This approach gives you full control over payment collection while still benefiting from Hyperline's billing and subscription management features. # Payout reconciliation Source: https://docs.hyperline.co/docs/payments/payouts Reconcile payment service provider payouts against bank account transactions in Hyperline, with grouped payment matching and finance overviews. Payout reconciliation helps you understand how money received in your bank account maps back to the payment transactions processed through a Payment Service Provider (PSP). When Hyperline detects a provider payout on a connected bank account transaction, it groups the matching payment transactions and displays the payout directly in the **Transactions** section. This gives finance teams a clear view of the gross amount collected, provider fees, and net amount included in the payout. Payout reconciliation is currently available for automatic Stripe payouts paid into a connected bank account. ## Before you start To use payout reconciliation, make sure that: * Your Stripe account is connected in **Settings** > **Payment** * The bank account receiving Stripe payouts is connected to Hyperline * Bank account transaction synchronization is active * The related Hyperline payment transactions are settled If you still need to connect a bank account, see [Reconciliation](../invoices/reconciliations#connected-bank-account). ## How Hyperline matches payouts After each bank transaction refresh, Hyperline looks for incoming bank transactions that can represent a provider payout. For Stripe payouts, Hyperline matches a bank transaction when: * The transaction is posted and incoming * The bank transaction label identifies Stripe * The amount and currency match one automatic Stripe payout * The Stripe payout arrival date is close to the bank transaction date * The payout contains settled payment transactions already recorded in Hyperline If several Stripe payouts could match the same bank transaction, Hyperline does not attach one automatically. This avoids linking the bank movement to the wrong provider payout. ## Review payouts Go to **Transactions** > **Connected Bank Accounts** to review bank account activity. Rows matched to a provider payout show a provider payout tag, such as **Stripe payout**, instead of the raw bank transaction label. Hover over the tag to see: * The original bank transaction description * The number of matched transactions * The payout arrival date Click the row to open the transaction drawer. The payout section shows: | Field | Description | | - | - | | **Provider** | The payment provider that issued the payout | | **Payout ID** | The provider payout identifier | | **Arrival date** | The payout arrival date reported by the provider | | **Matched at** | When Hyperline matched the bank transaction to the payout | | **Payout amount** | The total payout amount received from the provider | | **Provider fees** | The total fees included in the matched payout lines | | **Net included** | The total net amount included in the matched payout lines | | **Transactions** | The number of Hyperline payment transactions included in the payout | The side panel lists the matched transactions. Use it to confirm which customer payments and refunds are included in the payout before exporting or reconciling the bank movement in your finance workflow. ## What to do when a payout is missing If an expected payout does not appear as matched: * Check that the destination bank account is connected and syncing successfully * Confirm that the payout is an automatic Stripe payout * Confirm that the payout amount and currency match the bank transaction * Wait for the next bank transaction refresh if the payout has just arrived * Check whether the bank transaction is already linked to an invoice reconciliation If a payout still does not match, reach out via the in-app chat with the bank transaction date, amount, currency, and provider payout ID. ## Related pages * [Payment orchestration](./orchestration) * [Payment methods](./payment-methods) * [Invoice reconciliation](../invoices/reconciliations) # Scheduled transactions Source: https://docs.hyperline.co/docs/payments/scheduled-transactions Schedule future Hyperline transactions on a chosen payment method and date. Useful for installments or splitting an invoice across methods. Hyperline allows you to schedule a transaction with a specific payment method at a custom future date, for a custom amount. This is particularly helpful to create payment installments for customers who wish to pay the invoice in multiple installments. You can schedule a transaction on any payment method allowed for a customer, so you can use multiple methods for the same invoice. ## Schedule a transaction You can access it while creating a new invoice, editing an invoice or by clicking **Schedule transactions** in the **Transactions** section. You can only schedule transactions on draft, to pay and partially paid invoices. ## Edit a transaction You can edit all transactions after they have been created but before they are executed, as long as they are in a `scheduled` status. You can edit all transactions with a manual payment method (bank transfer, outside of Hyperline) afterwards without any limitations. ## Execute transactions Hyperline processes transactions with automated payment methods at **the beginning of each hour**, after the scheduled process date has passed. # Price books Source: https://docs.hyperline.co/docs/price-books/overview Extend the Hyperline product catalog with price books, giving specific roles or customers tailored pricing on quotes and subscriptions. ## What is a price book? A price book is a named set of prices for products from your **Default catalog**. Use price books when different teams or customers need different pricing without changing your main catalog. You create an **EMEA pricing 2025** price book with lower seat prices, grant it to your **Account manager** role, and set it as the default price book on European customers. When an account manager creates a quote, that book is preselected and they only see prices from it. ## Create a price book To create a price book, go to the [products section](https://app.hyperline.co/app/products) of the Hyperline interface. From **Catalog > Products**, open the dropdown that shows **Default catalog**, then select **New pricebook**. Enter a **Name** and, if needed, a **Description**. Configure **Access** for the roles that should use this price book. The price book is created empty. Add products from the **Default catalog** to define its prices. ## Add and manage prices in a price book Price books only include products you add to them. Each added product is a copy of the **Default catalog** product with its own price configurations. Selected products are imported with their current **Default catalog** prices. Once products are added, you can edit or delete prices in the price book without changing the **Default catalog**. In a price book, you can only edit prices. Product names, descriptions, and other catalog fields are shown for reference, and you must update them from the **Default catalog**. Adding a product to a price book copies its prices at that moment. Later changes to **Default catalog** prices are not applied automatically to existing price book copies. [Entitlements](../entitlements/overview) and other product grants stay on the catalog product and are shared across all price books that include it. To remove a product from a price book, open the product in the price book, click **Actions**, then **Remove from pricebook**. This deletes the price book prices for that product but keeps the product in the **Default catalog**. ## Edit or delete a price book Open the price book from **Catalog > Products**, then use **Actions**: | Action | What it does | | - | - | | **Edit pricebook** | Update the name, description, and role **Access** toggles | | **Delete pricebook** | Permanently delete the price book | You can only delete a price book that is not assigned to any customer. If a customer still uses it as their default price book, deletion is blocked. ## Assign a price book to a customer When a customer has a default price book, Hyperline preselects it when you create a quote or subscription for them. In **Advanced**, select the price book. Leave it on **Default catalog** if the customer should use your standard catalog prices. Hyperline updates the customer's default price book for future quotes and subscriptions. ## Grant a price book to a role Role access controls who can use a price book when assigning subscriptions or creating invoices. It does not change who can view or edit the catalog itself. You configure access on the price book, not from **Settings > Team > Roles**. When you create or edit a price book, use the **Access** section to turn each role on or off. When you create a price book, all roles are enabled by default. Turn off any role that should not use the book. To change access later, open the price book from **Catalog > Products**, click **Actions**, then **Edit pricebook**, and update the **Access** toggles. The **Default catalog** is always available when selecting a price for a product, even if a user does not have access to a specific price book. Role access only applies to named price books. See [Users & permissions](../account/users-permissions) to create custom roles or adjust the **Manage products** permission. ## Use a price book on a quote or subscription When you add a product to a quote or subscription, you can select which price book applies to that line. If the customer has a default price book, it is preselected. Switch the **Price book** dropdown to **Default catalog** or to another price book your role can access. Hyperline then shows price configurations from the selected book. If the product is not in the selected price book, no catalog prices appear for that book. Add the product to the price book first, or select **Default catalog** or **Manual configuration** instead. After you select a price, the price book used for the line appears on the subscription or quote. The same price book selector is available when creating invoices that reference catalog products. # Products and prices Source: https://docs.hyperline.co/docs/products/overview Manage your product catalog in Hyperline: define products, pricing models, currencies, intervals, and reusable price configurations for billing. In Hyperline, a product represents anything you sell to your customers. This can be software, a capability, a service, etc. You manage these products in a **products catalog**. This interface gives you a complete overview of your offering. It lets you manage the associated, reusable prices in a single place, based on various parameters (currency, location, market, interval, duration, etc.). Setting up products lets you create pre-configured plans, subscriptions, or one-time payments for your customers. Products can also grant [features and entitlements](../entitlements/overview), such as access to an integration, included seats, or a usage limit. Use product entitlements when a billed product should also define what the customer can access. ## Accounting mappings Use the product **Accounting** section to map a product to the external accounting record used by your accounting integration. Hyperline uses these mappings when it sends invoice lines to connected accounting providers. Depending on the connected provider, you can configure: | Field | What it controls | | - | - | | **Product code** | The product, item, or service identifier sent to the accounting provider for invoice lines using this product. | | **Account code** | The GL account code used by integrations that read account codes directly from the product. | ### Bulk update accounting mappings When you need to update several products at once, use the product catalog bulk action instead of opening each product individually: 1. Go to **Catalog** > **Products**. 2. Select the products you want to update. 3. Click **Bulk update**. 4. Update the accounting fields, such as **Product code** or **Account code**. 5. Click **Save**. Map products before running a first invoice sync. Missing product mappings can stop synchronization until the affected products are corrected and retried. ## Types of product Hyperline lets you represent a variety of products for sale using the following product types. ### Fee A "flat fee product" refers to a product or service for which the cost is a **fixed**, **consistent charge**. It means that the customer or client pays a predetermined, flat fee, regardless of usage, quantity, or time duration. This contrasts with usage periods where the cost may fluctuate based on factors like usage, consumption, or time. You can use this product for **subscription fees**, **fixed-rate services**, **addon items**, or **additional fixed costs**. This provides predictability for your customer, as they know exactly how much they will pay without unexpected variations in costs. For example, you can use this product to bill a fixed platform access to software, or an onboarding fee. This type of product can be: * included in subscriptions using the **Allow product to be added to a subscription** option * billed separately using the **Allow this product to be charged as a one-time payment** option **Pricing model** This product supports [flat fee](#flat-fee) prices. ### Seat A "seat product" refers to a type of licensing where the cost of a software application or service depends on a number of items. These items are called "seats" (users, accesses, licenses, etc.). This kind of product allows scalability, where customers can add or remove seats as needed, making it flexible for businesses with changing requirements. For example, you can use this product to bill a specific number of user licenses. Each license allows one person to use the software or service. This type of product can be included in subscriptions with the ability to link to product data for automatic adjustment of billable items or manual configuration. Seat products also support **connected seats**, where the seat count is automatically tracked via an [aggregator](/docs/usage/aggregators) (count operation). This enables automated metering with background updates and customized payment terms, such as yearly pro-rated charges based on peak user counts. Learn more about connected seats in our [Automated seat-based billing](/docs/subscriptions/connected-seats) guide. **Pricing models** This product supports [volume](#volume), [bulk](#bulk), and [bundle](#bundle-pricing) prices. ### Usage A "usage-based product" refers to a type of product where the cost is directly tied to how much your customer uses or consumes the product. In this model, customers are typically charged based on their actual usage, rather than a flat fee. This kind of product offers flexibility, allowing customers to pay for what they actually use with a cost varying with the amount or extent of usage. It enables a "pay-as-you-go" or "pay-per-use" model where customers are billed periodically based on their usage during that period. For example, you can use this product to bill data transfer in gigabytes, cloud computing in CPU hours, or the number of API calls in a SaaS product. This type of product relies on usage data measured using `events`, which represent specific occurrences to bill during a given period. Hyperline also provides detailed usage reports, making billing transparent and providing clarity on how charges are calculated. **Pricing models** This product supports [volume](#volume), [bulk](#bulk), and [basis points (BPS)](#basis-points-bps) prices. #### Metering configuration A usage-based product must be linked to an [aggregator](/docs/usage/aggregators) that defines how events are transformed into a billable metric. Aggregators support two operations: **count** (number of events) and **sum** (total of a numeric property). You can configure additional filters on the aggregator to narrow down eligible events based on custom fields (strings, numbers, or booleans) from your system. **Price metering filters** In addition to configuring metering for the product, you can set metering filters for each price. This allows you to define pricing based on specific criteria, enabling complex pricing matrices and price points based on specific usage parameters and values. For example, if you offer cloud computing services, you can apply different prices based on compute instance type or region. Similarly, if you process banking transactions, you can apply specific fees depending on the scheme or card configuration. ### Credit A "credit product" represents a granted quota that customers can pay for upfront and consume over time. Each customer has a **single shared balance** that is automatically debited as eligible usage events come in, so credits act as a prepaid layer on top of your usage data. This kind of product is useful when you want to decouple purchase from consumption. Customers buy a quantity of credits, and any combination of metered actions draws from the same balance until it is exhausted or topped up. For example, you can use this product to bill AI inference time. Each GPT-4 request consumes 5 credits, each GPT-3 request consumes 1 credit, and each image generation consumes 10 credits, all from the same balance. A credit product is linked to one or more [aggregators](/docs/usage/aggregators), each with a **weight** that defines how many credits one unit of usage consumes. All aggregators draw from the same balance. **Pricing models** This product supports [volume](#volume), [bulk](#bulk), and [bundle](#bundle-pricing) prices: * **Volume** applies progressive prices across quantity tiers. * **Bulk** uses the tier reached by the total quantity to price all credits. * **Bundle** offers predefined quantity and price combinations. When you add the product to a plan or subscription, Hyperline uses the assigned credit quantity and the selected catalog price to calculate the amount. The resulting amount is stored as a fixed fee on the subscription while retaining its catalog pricing context. For the full setup flow, customer-level balance management, expiration rules, and auto-topup, see [Set up credits on your account](/docs/credits/overview). ### Bundle A "bundle product" groups several existing products into a single offering, sold to your customers as one logical unit. This is useful when you want to package complementary products together and bill them as a single item. For example, you can combine a base subscription with a quota of API calls and a number of seats. Don't confuse a **bundle product** (a product *type*, described here) with **bundle pricing** (a *pricing model*, described [below](#bundle-pricing)). A bundle product wraps multiple products together; bundle pricing offers predefined quantity/price packages on a single product. The two are independent and can be used separately. **Components and revenue allocation** A bundle is composed of one or more **components**, each pointing to an existing product in your catalog (any type: fee, seat, or usage). Each component carries a **percentage** that defines how the bundle's revenue is allocated to that product. The percentages of all components must sum to 100%. This allocation drives revenue recognition (each component's share is recognized against the underlying product) and, when configured, the per-line breakdown shown to your customers on the invoice. **Display mode** Bundles support two display modes that control how they appear on invoices: * **Single line**: the bundle is shown as one line item on the invoice. The component breakdown is tracked internally for reporting and accounting, but the customer only sees the bundle as a whole. * **Ventilated**: each component is shown as its own line item on the invoice, with amounts split according to the configured percentages. Use this when your customers expect to see exactly what is included in the bundle and at which value. **Exclusive components** Bundles offer an option to mark their components as **exclusive to the bundle**. When enabled, the underlying products can only be sold as part of this bundle and won't appear on their own in quotes or subscriptions. Disable this option if you also want to sell the same products independently outside of the bundle. **Pricing models** This product supports [volume](#volume), [bulk](#bulk), [packaged](#packaged), and [bundle](#bundle-pricing) prices. *** ## Pricing models Products in Hyperline support a variety of pricing models: **flat fee** pricing, **volume** pricing, **bulk** pricing, **bundle** pricing, and **basis points (BPS)** pricing. ### Parameters Each product can also contain multiple prices (of different models) depending on different parameters: **currency**, **country**, **interval**, and **commitment** period. This enables you to represent all the cases you propose with fine granularity. You can adapt prices to the specific characteristics of the markets you operate in, or to your customers' engagement with your service. In the example above, the product costs 200€ per month, except for UK customers where it's 220£ per month. On a yearly interval, it costs 2200€ per year, except for customers committed for 2 years where the price is reduced to 2000€ per year. The more specific or narrowed parameter values (such as a specific country or a specific commitment period) take precedence over the broader values (such as "all"). ### Flat fee Predetermined, fixed and unchanging price. ### Volume Cost per unit or item is adjusted proportionally to the quantity of items purchased or consumed. Usually, the more a customer buys, the lower the cost per unit becomes. Volume pricing often involves multiple price tiers, which can be used to change the price depending on certain volume thresholds. In the example above, the customer pays 50€ per unit between 0 and 10, then 40€ per unit between 10 and 50, then 20€ per unit. That's 2360€ for 63 units. Hyperline shows a preview of how the price evolves with quantity, which helps you see the overall trend. It also previews how the price renders for your customer (e.g. on their checkout page). #### Pay tier in full You can activate the "Pay tier in full" option on a per-tier basis. This option allows you to charge the full price of the tier (i.e. `price per unit` `⨉` `to` value) if the consumption is contained in this tier range. In the example above, the customer is billed 250€ for this product between 0 and 5 units regardless of their consumption, then a progressive price for higher levels (e.g. 370€ for 9 units). ### Packaged Like volume pricing, packaged pricing is adjusted proportionally to the quantity of items purchased or consumed, usually involving multiple price tiers. The difference is that you can define packages of units, allowing you to define a price for a quantity of items inside a specific tier. In the example above, the customer is billed 6€ per 20 units if less than or equal to 200, then 4€ per 20 units if more than 200 (e.g. 100€ for 400 units). ### Bulk The total number of units determines the tier used and therefore the cost of all units. Reaching a higher tier value will decrease the price per unit. In the example above, the customer pays 50€ per unit for 10 units or fewer, or 30€ per unit for more than 10 units. That's 1020€ for 34 units. As with volume pricing, the "Pay tier in full" is also available, and Hyperline shows an overview of the price evolution and final rendering on the customer's checkout page. ### Bundle pricing Bundle pricing allows you to configure predefined bundles with specific quantity/price combinations. This model is particularly useful for seat-based products where you want to offer only specific package options to customers. With bundle pricing, customers can only select from the predefined bundles you configure when creating quotes and subscriptions, rather than choosing any arbitrary quantity. A software company offers user licenses in predefined bundles: 5 seats for $100, 10 seats for $180, or 25 seats for \$400. Customers must choose one of these exact bundles rather than selecting a custom number of seats. This pricing model is also used for credit products, where you can define packages of credits at fixed prices (e.g., 1000 credits for $50, 5000 credits for $200). ### Basis points (BPS) Method used to calculate prices based on a given percentage applied on the number of items considered in the computation (i.e. usage billed for the period). You can define tiers to vary this percentage. As with volume pricing, the "Pay tier in full" is also available, and Hyperline shows an overview of the price evolution and final rendering on the customer's checkout page. ## Translating product names If you have an international audience, it's important to have your products correctly translated on invoices and hosted pages. On the product page, you can add translations for the name and the public description by clicking the globe icon. Once you save, Hyperline updates the portal and checkout, and new invoices use the translations when appropriate. ### Hosted pages rules On hosted pages, Hyperline uses translations in the following order of priority: * Customer's browser language (if the customer has defined Italian as their primary language, Hyperline uses Italian translations) * Customer's language set on Hyperline * Customer's country (if the customer's address is in Italy, Hyperline uses Italian translations) * English * Default product name # Custom properties Source: https://docs.hyperline.co/docs/properties/overview Define custom properties in Hyperline to store extra data on customers, products, subscriptions, and invoices, and use them across templates. Flexibility and customization are key aspects of Hyperline. Custom properties let you represent and store all the extra data you need. You can define custom properties and associate them with **customer**, **product**, **subscription**, and **invoice** entities. You can also use subscription custom properties in subscription templates. Custom property values support a range of types, including **text, email, number, boolean, date, select, and multi-select**. ### Use cases Custom properties provide a wide range of possibilities. For example, you can use them to represent additional fields for your customers or integrate extra billing details into your subscriptions or subscription templates. They can also assist in entitlement and feature flagging by representing features activatable on specific products or subscriptions. Invoice custom properties can also scope both [accounting rules](../accounting/rules#custom-property-filters) and the [sync rules](../accounting/rules#accounting-software-sync-rules) of your accounting integration. For example, you can post revenue to a different account per business unit. These are just examples, and you can customize them to meet any specific needs based on your use case. ## Create a custom property Enter a name, a slug, the property type, and the entities on which the custom property will be available. The slug is a unique identifier mainly used for technical integration using the API. You can also set a [default value](#setting-a-default-value) and make the property required so that each selected entity must have a value. Additionally, you can activate this custom property for technical purposes only. In that case, you can't edit it in Hyperline's interface, and it's only available through the API. When you turn this option off, you can edit the field in both the interface and the API. ## Email properties Use the **Email** type to store an email address, such as a billing contact or an account manager. Hyperline validates email property values as email addresses: * When you set a [default value](#setting-a-default-value), it must be a valid email address. * When you edit an entity's custom properties, Hyperline blocks saving until the value is a valid email address. You can clear the value of an optional email property by leaving the field empty. Email properties behave like text properties elsewhere in Hyperline. You can use them in list filters, [customer segments](../customers/segments), [accounting rules](../accounting/rules#custom-property-filters), and [approval workflow conditions](/docs/account/approvals#rules). They also appear on hosted quotes and PDFs. ## Requiring a custom property value Enable **Required** when every entity associated with the custom property must have a value. Hyperline then prevents users from creating or saving an associated customer, product, subscription, or invoice until they provide one. If you make a custom property required after entities already exist, Hyperline doesn't immediately change those entities. The next time a user edits or saves one, they must provide the missing value before they can continue. This also applies when the edit is unrelated to custom properties, such as changing an invoice status. A required custom property marked as **API only** can't be completed in the interface. Make sure your integration provides the value through the API whenever it creates or updates an associated entity. Before making a select or multi-select property required, configure at least one available value so your team can complete the field. ## Setting a default value Set a **Default value** on a custom property to fill it automatically on new entities. The input follows the property type: for select and multi-select properties, select from the available values. When a customer, product, plan, subscription, or invoice is created without a value for the property, Hyperline stores the default value: * On the subscription and invoice creation forms, Hyperline prefills the field with the default value. You can change it before saving. * Customers, products, and plans don't show custom properties at creation. Hyperline applies the default value automatically. * Entities created through the API or an integration get the default value when they don't provide one. A value provided explicitly always takes precedence over the default value. Hyperline doesn't update existing entities when you set or change a default value. You add a required **Region** property on customers with `EU` as the default value. Customers created from now on get `EU` unless another region is provided. Your existing integrations keep creating customers without sending the new property. ### Default values and required properties When a required property has a default value, you can create an entity without providing a value. Hyperline uses the default value instead. Hyperline also doesn't block updates to existing entities that have no value, so integrations keep working after you make a property required. You still can't clear the value on purpose. Hyperline doesn't write the default value to existing entities. They keep an empty value until someone provides one. The interface still asks for a value when a user edits one of these entities. ## Managing custom property values After you create a custom property, you can find it on the related entity in the interface. On the **customer**, the custom properties appear at the bottom of the information panel on the customer details page. For **products**, they appear in a dedicated box on the product in the **Advanced settings** section. For **subscriptions**, you can set the value in the second step of the subscription assignment flow. The same subscription custom properties are available when configuring a subscription template. For **invoices**, you can set the values from the invoice details when creating or editing an invoice. When Hyperline generates an invoice from a subscription, it automatically copies the subscription's custom property values to the invoice. This happens when the same custom property is available on both entities. You can still edit the invoice value afterward when the invoice can be updated. Automatic copying only applies to custom properties that are available on both the **subscription** and **invoice** entities. ## Filtering by custom properties You can filter customers, subscriptions, and invoices by their custom property values in the respective list views. When you create custom properties for customers, subscriptions, or invoices, filter controls automatically appear in the filters dropdown on the **Customers**, **Subscriptions**, and **Invoices** pages. The filter type depends on the custom property type: * **Boolean properties**: Display as a dropdown with **On** and **Off** options * **Select properties**: Display as a dropdown with the predefined values you configured * **Text and email properties**: Display as a text input that matches values containing what you type To filter by custom properties: 1. Navigate to the **Customers**, **Subscriptions**, or **Invoices** page 2. Click the filters dropdown 3. Select the custom property filter you want to apply 4. Select the value to filter by The list automatically updates to show only records matching your selected criteria. Custom properties marked as **API only** don't appear in the filter panel. ## Displaying custom properties on hosted pages This is currently only available for the **customer** portal page. You can select which custom properties to display on the customer portal by navigating to the **Settings** > **Hosted pages** section. ## Using the API You can [create](../../api-reference/endpoints/custom-properties/create-custom-property), [retrieve](../../api-reference/endpoints/custom-properties/list-custom-properties) and [manage](../../api-reference/endpoints/custom-properties/update-custom-property) custom properties using the API. Additionally, you can retrieve the values using the `custom_properties` field when fetching a [customer](../../api-reference/endpoints/customers/get-customer), [product](../../api-reference/endpoints/products/get-product), [subscription](../../api-reference/endpoints/subscriptions/get-subscription), or [invoice](../../api-reference/endpoints/invoices/get-invoice). You can also set invoice custom properties when you [create](../../api-reference/endpoints/invoices/create-invoice) or [update](../../api-reference/endpoints/invoices/update-invoice) an invoice through the API. Subscription template configurations use the same `custom_properties` field as subscriptions when you [create](../../api-reference/endpoints/subscriptions->-templates/create-subscription-template-configuration) or [update](../../api-reference/endpoints/subscriptions->-templates/update-subscription-template-configuration) a configuration through the API. ### How this differs from the `properties` field Hyperline introduced the `properties` field first, but it lacks structure (for example, it isn't named or typed). Non-technical users also can't manage it through the interface. While you can still use this field to store unstructured technical details on supported entities, use custom properties when possible to ensure safety and better manageability. # Quote approvals Source: https://docs.hyperline.co/docs/quotes/approval Submit and review quotes for approval before sending them to customers, with quote-specific rules and manager approvals. Quote approvals let your team review commercial terms before you send a quote to a customer for signature. Start with [Approval workflows](/docs/account/approvals) to configure shared rules, approval steps, priority, notifications, and delegations. This page covers the options and approval process specific to quotes. ## Configure quote approvals Follow the [workflow setup steps](/docs/account/approvals#configure-approval-workflows) and select one or more quote flows under **Applicable flows**: * **Quote for new subscription** * **Quote for subscription update** * **Quote for one-off invoice** Alongside the [shared conditions](/docs/account/approvals#rules), quote workflows can use contract clauses, modified contract clauses, terms and conditions, and whether a quote has an attachment. Subscription quote flows can also use the subscription template, billing period, free trial, contract auto-renew, and subscription [custom properties](/docs/properties/overview). Custom property conditions support text, email, number, boolean, select, and multi-select properties. Number properties support comparison operators. Other types, including email, support **equals** and **not equals**. Date properties are not available as conditions, and select or multi-select properties need at least one configured value. For payment method conditions, subscription quotes use the customer's payment method. One-off quotes use the payment method selected on the linked invoice. Require a legal review when a salesperson modifies a standard contract clause. You can select clauses from your [quote templates](/docs/quotes/templates) and use the modified-clause condition to trigger approval. ### Manager of quote owner Rather than naming approvers explicitly, a step can require approval from the manager of the quote owner. Hyperline resolves that manager every time approval is requested, from the manager set on the owner's member profile. See [Set a member's manager](/docs/account/users-permissions#set-a-members-manager). This keeps a single workflow valid across an entire sales team, so you don't need one workflow per team. Hyperline routes every quote to its own owner's manager. Hyperline notifies the resolved manager, who reviews the quote like any other approver. You can combine this option with individual approvers and roles on the same step. One workflow requires approval when the discount exceeds 20%, with a single step set to **Manager of quote owner**. A quote owned by a rep in the EMEA team goes to the EMEA manager, while the same workflow routes a US rep's quote to the US manager. Good to know: * Changing a member's manager while a quote is pending approval hands the step to the new manager, who is notified. * To change the owner of a quote pending approval, click **Edit quote**, change **Owner** in the editor footer next to **Save**, click **Save**, then click **Finalize quote**. Editing moves the quote back to draft and cancels the pending request, and finalizing starts a new request routed to the new owner's manager. Changing the owner requires the **Manage quote owner** permission. * A quote owner can never approve their own quote through this option, since a member cannot be their own manager. * If the quote owner has no manager and the step also names members or roles, those approvers still decide the step. * If the step that cannot resolve is followed by a step with approvers, the quote opens on the first step somebody can decide. * A manager whose membership is archived or deactivated counts as no manager. When the manager is a step's only approver and the quote owner has no manager, nobody is left to decide that step. If no other step requires a decision, the quote is approved without review. This also applies to a quote already pending approval when its owner loses their manager, for example when the manager is cleared or their access is revoked. Add a fallback member or role to the same step whenever it must always be reviewed. For team departures, see [When an approver leaves](/docs/account/approvals#when-an-approver-leaves). ## Approval process ### For quote creators 1. Create your quote and click **Finalize quote**. 2. Review the approval requirements. If approval is required, you can add an optional **Comment for approvers** to explain the context, then click **Finalize**. The quote moves to `Pending approval`. 3. Open the quote to see which workflow was triggered and the active approval step. 4. Wait for the review. You receive an email when the quote is approved or when an approver rejects it and requests changes. 5. After approval, [send the quote to your customer](/docs/quotes/overview#send-quote) for signature. If changes are requested, click **Edit quote**, address the feedback, then click **Finalize quote** to resubmit it for approval. You can also void the quote if you decide not to proceed. ### For approvers 1. Open the quote from your approval notification, or use the **Need your approval** tab in the quotes list. 2. Review the quote details, any comment from the creator, and the approval history. 3. Click **Approve**, optionally add an **Internal comment** for the creator and other approvers, then click **Approve** to confirm your decision. To request changes instead, click **Reject** and enter a **Reason** for the creator. After the final approval step, the quote is ready to send. If you reject it, Hyperline notifies the creator, who must edit or void it. You can also act directly from a Slack approval notification. Quote notifications include the quote PDF in a thread. See [Notifications](/docs/account/approvals#notifications) for setup. ### Internal comments Use comments to explain a request or record the context behind an approval. Comments are optional and visible only internally, not to your customer. * The creator's **Comment for approvers** appears in the quote's approval section and history, and in approval request notifications sent by email or Slack. * An approver's **Internal comment** is saved with their decision and appears in the quote history. When submitting a quote with a 25% discount, add: "Discount negotiated in exchange for a two-year commitment." The approver can then record: "Approved based on the agreed contract term." ## Quote statuses | Status | Meaning | | - | - | | `Pending approval` | The quote is waiting for approval at one or more steps. | | `Changes requested` | An approver rejected the quote and requested changes. Edit and resubmit the quote, or void it. | | `Ready to send` | All approval steps are complete. You can send the quote to the customer for signature. | Filter the quotes list by **Pending approval** or **Ready to send**, or use the **Need your approval** tab to find quotes waiting for your review. ## Simple quote approval permission When approval workflows are not enabled, Hyperline provides a dedicated **quote approval permission**. If a team member without this permission creates and validates a quote in Hyperline or a connected CRM, the quote moves to `Pending approval`. A team member with the approval permission must approve it before it can be sent for signature. This simple approval flow does not automatically notify team members with the quote approval permission. You can set up notifications with an external workflow tool such as [Zapier](/integrations/zapier). For custom integrations, share the [webhook documentation](/developers/webhooks) with your technical team; the relevant event is `quote.approval_requested`. ## Next steps * [Configure approval workflows and delegations](/docs/account/approvals). * [Send a quote for signature](/docs/quotes/signature). # Quote for one-off invoice Source: https://docs.hyperline.co/docs/quotes/one-off-invoice Create a quote for one-time fees, configure when the invoice is issued, and choose whether to review a draft after signature. Create a quote for a one-off invoice when you need a customer to approve a non-recurring charge, such as an implementation fee, project work, or a one-time purchase. This flow does not create a recurring subscription. You quote a €2,000 implementation fee. The customer signs the quote, then Hyperline finalizes the invoice for payment. If your finance team needs to review it first, you can keep the invoice as a draft after signature. ## Create a quote for a one-off invoice 1. Open the [**Quotes** page](https://app.hyperline.co/app/quoting/quotes), click **Create quote**, and select **Quote for one-off invoice**. 2. Select the customer. 3. In the quote editor, click **Add invoice** to configure the invoice. 4. Add products from your catalog and set their quantities and unit prices. Add [coupons](/docs/invoices/manage#apply-coupons) if needed, and review the invoice period, purchase order, and customer note. 5. Configure the **Issue date** as described below, then click **Save invoice**. You can add any product from your catalog. Whatever its usual pricing model, it is charged as a fixed amount (quantity × unit price) on this invoice. Recurring billing and usage-based pricing are not calculated automatically. ### Choose when to issue the invoice By default, **Issue date** is set to **On quote signature**. You can select a future date instead. Hyperline waits until the quote is signed before issuing the invoice. If the selected date has already passed when the customer signs the quote, Hyperline finalizes the invoice at signature. In the quote editor's **Generate draft invoice** section, turn on **Keep invoice as draft after signature** if you want to review and finalize the invoice manually. | Configuration | What happens after signature | | - | - | | **On quote signature**, with the draft option off | Hyperline finalizes the invoice at signature. | | Future **Issue date**, with the draft option off | Hyperline schedules the invoice for that date, or finalizes it at signature if the date has already passed. | | **Keep invoice as draft after signature** on | The invoice stays in `draft` until you finalize it manually, even if you selected a future issue date. | ### Complete the quote 1. Configure the quote owner, expiration date, and information the customer must provide before signing, such as billing details or a payment method. 2. Review the quote value and choose whether to display it to the customer. 3. Add a customer note, contract terms, and any supporting documents. 4. Review the quote preview, including the invoice details, then finalize the quote when it is ready. See [Create and send quotes](/docs/quotes/overview) for the shared quote settings and document options. If the quote requires [approval](/docs/quotes/approval), it moves to `Pending approval` before you can send it. Once approved, it is ready to send. Saving a quote as a draft does not make it available for signature. ## Send the quote Once the quote is `Ready to send`, select one of these actions: * **Send quote** to email it from Hyperline and track email delivery and openings. * **Generate public link** to share it yourself. Hyperline does not track delivery or openings of an email you send outside Hyperline. The quote then moves to `Pending signature`. Your customer can review the quote, provide any required information, and sign it. See [Quote signature](/docs/quotes/signature) for the available signature methods, including signing outside Hyperline. ## Edit a quote before signature 1. Open the quote and select **Actions** > **Edit quote**. This returns it to `draft` and disables its public link. 2. To change the invoice, click **Configure invoice** in the quote editor, make your changes, and click **Save invoice**. You do not need to delete the quote. 3. Finalize the updated quote, complete any required approval, then use **Send quote** or **Generate public link** to make it available to the customer again. If you use a [signature workflow](/docs/quotes/signature/workflow), editing a quote discards any signatures already collected. All signers must sign again. To extend the signing deadline without disabling the public link, use **Update expiration date** from the quote's actions instead of editing the entire quote. ## After signature Once the quote is fully signed, Hyperline creates the linked invoice according to your issue date and draft settings. You can open the invoice from the quote details page. If you kept the invoice as a draft, review it and select **Actions** > **Finalize invoice** when it is ready. Any applicable [invoice approval workflow](/docs/invoices/manage#require-approval-before-finalization) must complete before finalization. Finalizing an invoice makes it available for payment; it does not mean the customer has paid. Invoice emails and payment collection follow your configured settings. ## Next steps * [Manage invoices](/docs/invoices/manage) * [Invoice emails](/docs/invoices/emails) * [Payment methods](/docs/payments/payment-methods) # Create and send quotes Source: https://docs.hyperline.co/docs/quotes/overview Run a full CPQ process in Hyperline: configure products, set custom prices, generate quotes for signature, and auto-activate the subscription. Hyperline provides a **complete CPQ process**, allowing salespeople to configure products, set a pre-configured or custom price, and generate a quote ready for signature. This facilitates the internal approval process for customers. Once a quote is accepted and signed, Hyperline can automatically activate the related subscription, starting the billing and invoicing cycle without any manual actions required. ## Create new quote To create a quote, head to the **Quoting** section and click **Create quote**. You can save a quote as a draft and complete it later. You can create multiple quotes for the same customer. ### Quote template You can create quotes from an existing template, configured in the templates page. Learn more about [quote templates](./templates) on the dedicated documentation page. If you want to create a quote from scratch, select **Configure manually**. ### Name By default, Hyperline names the quote "Quote ". You can rename it the way you want, using variables for dates and next quote number. ### Settings * **Expiration date** After this date, the customer will still be able to access the quote but won't be able to sign it. In Settings > Quoting, you can allow your customer to still sign the quote by toggling the option "allowed signature after expiration" in the signature section. * **Quote owner** The salesperson responsible for the customer and contract. You can change this later in the process, and it may affect whether the quote requires approval based on your configured approval workflows. * **Require tax ID** Require company customers to provide a tax identifier before signing the quote. If local tax numbers are enabled for the invoicing entity, the customer can provide either a Tax ID or a local tax number. Validation and reverse charge enforcement are controlled from the invoicing entity's [tax settings](../invoices/tax-management#tax-enforcement-options). * **Custom properties** (if they are configured on your account) Additionally, you can require your customer to fill specific pre-configured [custom properties](../properties/overview) during the quote signature flow. This is useful for non-standard information collection, like country-specific details. * **Require payment method**, particularly useful when your customer pays by card or direct debit, as you can start invoicing and collect money directly once the quote is signed. * **Require shipping details** Request the customer to add their shipping details as a required part of the quote signature flow. ### Subscription Quotes must include a subscription in order to be sent. Clicking **Add subscription** opens the familiar subscription assignment flow: select plan, configure contract and invoicing settings, add products, customize price configurations, add coupons. See more details in the [assign subscription](../subscriptions/create) dedicated page. You can create a quote for a [one-off invoice](./one-off-invoice) or a [subscription update](./subscription-update) following a different flow. ### Quote value Every quote created must have a set value. You can hide this information from the customer on the quote public page and PDF. Quote Value By default, Hyperline automatically calculates the quote value based on product prices, billing intervals, committed amounts, coupons, and the subscription or phase duration. You can edit this value to reflect a commercial adjustment that is not captured by the subscription configuration. For usage-based products, Hyperline includes committed amounts in the quote value. Future usage beyond the committed amount is not estimated automatically. The quote value only takes into account coupons with a duration > 12 months. If needed, manually edit the quote value to reflect the discount applied by the coupon. ### Additional information These fields are rich text fields, where you can style text to structure information, emphasize details and add hyperlinks. Both fields can be pre-configured in the quote template. Quote Value * **Note for customer** Freely add text to the quote header. Use it to give contextual information to the customer ahead of signature. * **Contract terms** Contract terms appear after the subscription details. Use them to give contractual information. Additionally, you can add pre-configured clauses to the quote by selecting them in the **Add from existing clause** selector. You can also use added clauses in [approval workflows](./approval), including when their text is modified before validation. ### Documents When creating or editing a quote, you can attach documents in the additional information section. This allows you to include custom files such as terms of use or any other relevant document. These attachments can be directly displayed on the quote public page and PDF if the option is selected. * **Accepted formats** `PDF`, `DOC`, and `DOCX`. Hyperline automatically converts Word documents to a signable PDF on upload, so they embed inline in the customer preview alongside PDFs. * **Maximum file size** 5 MB per file. * **Multiple files** You can select several files at once from the file picker, and drag documents to reorder them. The order defined here is the order shown to the customer. ### Display You can modify the information displayed on the quote by clicking the **Display** button in the bottom floating bar. You can configure all of these in the quote template. For general quote settings, you can show or hide the **first invoice amount**, **quote value**, and **documents preview**. For the subscription preview, you can show or hide **phase value** and **taxes**, and configure how **price tiers** are displayed. ### Custom quote layout (beta) Update the quote layout the way you want with a "what you see is what you get" approach, making the quote as easy to customize as a Notion document. Reorganize blocks, change the wording for all elements and add blocks anywhere. Custom Layout Enabling the custom layout fixes the quote in the customer language. It will no longer be dynamically translated based on the browser language. By default, the option is only enabled for Hyperline admins. You can change this in **Settings > Team > Roles > Edit**. ## Send quote Once finalized, the quote appears as `Ready to send`. At this stage, you can decide to: * **Send quote** by email to your customer, with a custom message in the email body. Hyperline tracks this email, so you can see every time the customer opens it. * **Generate public link** to share it with your customer in the way you prefer. After this, the quote will switch to a `Pending signature` status. Once sent, you can resend the quote by email whenever you want to remind your customer to sign it. Use the **Send quote** button in the **Actions** dropdown to resend it. ## Edit quote You can edit a quote anytime before the customer signs it by clicking **Edit quote** in the **Actions** dropdown. Editing the quote disables the public quote link and puts the quote back to the `Ready to send` status. ## Update expiration date You can update the quote expiration date at any time without editing the entire quote using the **Update expiration date** action. This is useful if you need to adjust the date following a discussion with your customer or after the quote has expired. This action will not disable the existing quote public link. ## Public link Hyperline offers a hosted public page to share a quote with your customer. On this page, the customer can view the entire quote details, access PDF attachments, fill in their billing details, and add their payment method (if required). The customer can also accept and sign the quote directly from this page. See more details in the [quote signature page](./signature). # Quote signature Source: https://docs.hyperline.co/docs/quotes/signature Collect customer signatures on Hyperline quotes: basic digital signature, DocuSign, Yousign, or countersigner workflows to formalize agreements. Hyperline natively offers a module where a customer reviews and formally accepts a quote by providing their digital signature. This action confirms their agreement to the terms, conditions, and pricing outlined in the quote, allowing the service or product subscription to commence as per the specified terms. ## Basic signature This is the default signature type used. This is the simplest form of signature offered by Hyperline. The signer simply needs to enter their name and tick a box to accept the quote (and any attachments). The basic signature doesn't have probative value but is useful if you need a simple and easy-to-implement quote confirmation step. ## Electronic signature Hyperline Signature allows your customer to sign the quote with probative value. It uses a secure electronic signature solution compliant with the eIDAS requirements. eIDAS is Regulation 910/2014 of the European Parliament and Council on electronic identification and trust services for electronic transactions in the internal market. The process is fully embedded into Hyperline and does not require additional configuration or implementation from you. For additional security, electronic signature requires a confirmation step with a verification code sent by email to the signer. Once the customer signs, an audit trail document is available on your quote details page. It provides proof of the legal signature's validity in case of any event such as a customer dispute. This feature is available on demand. Contact our support if you are interested. ### Yousign & DocuSign You can also use your own Yousign or DocuSign account to sign quotes. This is useful if you already have a Yousign or DocuSign account and want to use it to sign quotes. To use your own Yousign or DocuSign account, you need to connect it to your Hyperline account. 1. Go to **Settings > Integrations** 2. Click **Yousign** or **DocuSign** 3. Follow the instructions to connect your account 4. Update the signature provider to **Yousign** or **DocuSign** on the quotes settings page For Yousign, you need a Scale API plan. ### Countersigner When using electronic signatures, you can enable a countersigner in **Quoting > Settings**. Specify a name and an email address, typically someone from your organization. Once configured, Hyperline adds this countersigner to future quotes, after the customer's signature. With the default **Automatic** countersignature mode, Hyperline applies the countersignature with no action from your team. With **Manual**, the countersigner receives an email and signs the quote themselves. See [how countersignatures are given](/docs/quotes/signature/workflow#choose-how-countersignatures-are-given). This setting applies only to quotes created after the change. ### One-off countersigner If you need a countersigner for a single quote only, use the countersigner setting temporarily before creating that quote. 1. Go to **Quoting > Settings** 2. Enable **Countersigner** 3. Enter the countersigner name and email address 4. Create and send the quote that needs countersignature 5. Return to **Quoting > Settings** 6. Disable or remove the countersigner so future quotes use your usual signature flow Because countersigner settings apply only to quotes created after you change the setting, this does not update quotes that already exist. Keep the setting enabled only while you create the quote that needs countersignature. Any other quote created while the setting is enabled will use the same countersigner. With DocuSign, the countersigner is only available in a [signature workflow](/docs/quotes/signature/workflow#use-a-default-countersigner), where it signs manually. To collect several signatures on the same quote, in a set order and with internal countersignatures, use a [signature workflow](/docs/quotes/signature/workflow). ## External signature You may prefer to manage the signature process yourself, not use the Hyperline quote public page, or have your customer sign a file manually. In that case, Hyperline offers an option to mark an existing quote as signed manually. In this flow, Hyperline is not responsible for the signature. However, using the **Mark as signed** action, you can flag the quote as signed and optionally upload the corresponding PDF file. # Signature workflow Source: https://docs.hyperline.co/docs/quotes/signature/workflow Collect several signatures on one quote: signers in ordered steps, internal countersignatures, viewers, and who can open the quote. A signature workflow lets several people sign the same quote. You decide who signs, in which order, and who only needs to read it. Hyperline invites each signer when their turn comes, tracks every signature, and marks the quote as signed once the last signature is collected. The signature workflow is available on demand. Contact our support if you are interested. ## How it works A workflow is made of **steps**: * Signers in the **same step** can sign in any order, at the same time. * Steps run **one after the other**: the next step opens only when everyone in the current step has signed. * A step can end with a **countersignature** from someone in your team. Next to the signers, you can add **viewers**: people who receive the quote and can open it, but never sign. Your customer's CEO and CFO both need to sign, then your own sales director countersigns. * **Step 1**: the CEO and the CFO. Both receive the quote at the same time and can sign in any order. * **Step 2**: your sales director, as a countersignature. Hyperline asks them to sign only once the CEO and the CFO have both signed. * **Viewers**: the customer's procurement team, who follow the deal without signing. ## Set up the signers You can configure signers from the quote editor, with **Configure signers** in the signature block, or from the quote details page, with **Edit** in the **Signers** section. 1. In the first step, enter the signer's first name, last name and email. 2. Click **Add signer** to add another person to the same step. 3. Click **Add step** to add a step that opens once the previous one is fully signed. 4. Drag and drop steps to reorder them. 5. Click **Save changes**. Signers panel with two signers in one step and the Add countersignature toggle turned on With electronic signature, every signer needs a first and last name. With basic signature, an email address is enough: the signer types their name when they sign. A few rules apply: * Each email address can appear only once on a quote, either as a signer or as a viewer. * The workflow needs at least one customer signer. A countersignature always comes after a step with at least one signer. * Each step needs at least one signer or a countersignature. ### Add a countersignature A countersignature closes a step with a signature from your team, once every signer of that step has signed. 1. In the step, turn on **Add countersignature**. 2. Select one or more members of your team. 3. Click **Save changes**. The countersignature becomes its own step, right after the step it closes. With Hyperline Signature or Yousign, a member can be a countersigner only if their profile has a first and last name. Only the member can add these in their own profile. ### Use a default countersigner In **Quoting > Settings**, you can turn on **Countersigner** and enter the name and email of a default countersigner, typically someone from your organization: * On quotes sent **without** a signature workflow, Hyperline adds it as the second signer. * When you build a workflow, Hyperline adds it as the last step, tagged **Countersigner**. You can remove it from a specific quote with **Remove step**. With DocuSign, Hyperline only adds the default countersigner when you build a workflow. The countersigner always signs manually. ### Choose how countersignatures are given **Countersignature mode**, set under **Countersigner** in **Quoting > Settings**, controls what happens when a countersignature step is reached. It applies to every countersignature, including the team members you add to a workflow. | Mode | What happens | | - | - | | **Automatic** | Hyperline applies the countersignature automatically when its turn comes, with no action from your team. This is the default. | | **Manual** | The countersigner receives an email and signs the quote like any other signer. | Signature section of the quoting settings with the countersigner and the countersignature mode A change of mode also applies to quotes already out for signature. With DocuSign, countersignatures are always manual: DocuSign does not sign on someone's behalf. ## Add viewers Viewers receive the quote by email and can open and download it, but cannot sign or edit any details. 1. On the quote details page, click **Edit** in the **Viewers** section. 2. Enter an email address, then click **Add viewer** to add more. 3. Click **Save changes**. You can add or remove viewers at any time until the quote is signed or voided. A viewer added after the quote was sent receives the quote by email. ## Choose who can open the quote Each quote has a **visibility** that decides who can open its link: | Visibility | Who can open the quote | Who can sign | | - | - | - | | **Public** | Anyone with the link | Only signers, after confirming their email | | **Private** | Only viewers and signers | Only signers | To change it, open the quote's **Actions** and click **Set visibility**. You can switch at any time until the quote is signed or voided. Set visibility window with the Public and Private options New quotes use the **Default visibility** set in **Quoting > Settings**. Use **Private** when the quote must stay between the people you invited. Use **Public** when you share the link yourself, for example in a chat or in your CRM. ## Send the quote Once the quote is finalized, click **Send quote**. The **Send quote** window shows who is emailed: * **Notified now**: the viewers, and the signers of the first step that still needs signatures. * **Notified later**: the signers of the next steps. Hyperline emails each of them automatically when their step opens. Send quote window listing two signers notified now, a countersigner notified later and a viewer notified now You can add an optional custom message. Clicking **Send quote** again later only emails people who have not been notified yet. You can also click **Publish quote** to make the quote available without sending any email, and share its link yourself. Hyperline does not send reminders: once someone has been notified, sending the quote again does not email them a second time. ## What signers see ### Confirming their email When a signer opens the quote, they confirm their email address first: 1. They enter the email address the quote was sent to, and click **Send code**. 2. They receive a 6-digit access code by email, valid for 10 minutes. 3. They enter the code to open the quote. Access the quote window asking for the email address the quote was shared with Enter the access code window with six code boxes Once confirmed, they stay recognized for 24 hours. After 5 wrong codes, they need to wait 15 minutes before trying again. On a **Public** quote, anyone can read the quote without a code: signers confirm their email only when they click **Sign quote**. ### Signing Only the signers of the current step can sign. On the quote page, the signature block shows a **Sign quote** button for the current step, and every other signer as **Pending signature**. With **Hyperline Signature** or **Yousign**: 1. The signer clicks **Sign quote** and reviews the final document. 2. If they confirmed their email less than 30 minutes ago, they sign right away. 3. Otherwise, they click **Start signature** and enter the 4-digit verification code sent to their email. With **DocuSign**, the signer signs in DocuSign's signing screen, embedded in the quote page. After signing, the signer sees **Signature recorded** and how many other signers are still expected. Once the last signature is collected, the quote page shows the names of everyone who signed. Signature block with the Sign quote button and two pending signatures Signature block with one signature and two pending signatures If the quote requires payment details, they must be filled in before anyone can sign. Any customer signer can fill them in; viewers cannot. ## Track progress On the quote details page, the **Signers** section lists every signer in signing order with their status, and the **Viewers** section shows whether each viewer was notified. | Status | Meaning | | - | - | | `Pending` | Not invited yet: their step has not opened. | | `Notified` | Invited by email. | | `Viewed` | Opened the quote. | | `Signed` | Signed the quote. | Signers section with one signed, one notified and one pending signer, the Viewers section and the History The quote itself moves through these statuses: * `Pending signature` once it is sent or published. * `Partially signed` once at least one signer has signed. Your customers still see `Pending signature`. * `Signed` once the last signature is collected. The quote then follows its usual post-signature process, such as activating the subscription. The **History** section lists each signature, for example "Signed by Jane Doe" or "Countersigned automatically by John Smith". With electronic signature, the **Audit trail** of the signature is available in the **Additional documents** section once the quote is signed. ## Change the workflow after sending | Change | When it is possible | | - | - | | Add or remove viewers | Until the quote is signed or voided | | Change visibility | Until the quote is signed or voided | | Edit signers | With electronic signature, until the first signer starts signing. With basic signature, until the quote is signed. | | Reorder steps | Until the first signature is collected | | Remove a signer | Only if they have not signed yet | Once a signer starts signing with electronic signature, the signature request exists at the provider and the signers are locked. To change them, edit the quote: this starts a new signature workflow, and the signatures collected so far are discarded. Editing a quote that is out for signature discards every signature already collected. All signers will need to sign again. ## For developers * Hyperline sends the `quote.signed` webhook once the last signature is collected, not after each signature. * The API reports a partially signed quote as `pending_signature`. ## Related pages Signature types and providers Create and send quotes # Use Hyperline CPQ with Stripe Billing Source: https://docs.hyperline.co/docs/quotes/stripe-billing Integrate Hyperline CPQ with your existing Stripe Billing setup to give sales a robust quoting workflow while keeping Stripe as the billing engine. You can integrate Hyperline CPQ with Stripe Billing to provide your sales team with a robust CPQ solution. This gives your customers a seamless contractualization experience while maintaining your existing Stripe Billing setup. **Use Hyperline as your full billing platform** to take advantage of its advanced capabilities and reduce the operational complexity and limitations of external billing solutions. However, this integration still allows you to create and manage quotes directly from Hyperline and your CRM. Hyperline will automatically orchestrate the related subscriptions in Stripe Billing and process customer payments through Stripe Payments. With this setup, you can handle all data and billing activity monitoring in Hyperline, fully synced with your CRM. You continue to leverage Stripe Billing as your existing billing engine and payment gateway. ## How it works Hyperline provides powerful integrations with both Stripe and CRMs (HubSpot, Salesforce and Attio), alongside a complete CPQ solution. You can create quotes for new subscriptions or subscription changes (upsell, cross-sell, etc.) directly from your CRM using Hyperline's built-in widget, within Hyperline's interface, or via the Hyperline API. Once a quote is approved and signed by your customer, Hyperline automatically creates or updates the subscription in Stripe Billing, with no manual intervention or additional technical effort required. Stripe Billing then manages the full billing lifecycle and payment processing. Hyperline automatically syncs all subscription details and related invoices from Stripe in real time, so you can monitor billing activity directly from Hyperline. This data is also pushed to your CRM, giving your operational and revenue teams full visibility. ## Prerequisites * A Hyperline account with admin rights * A Stripe account with admin rights * CPQ and Stripe integrations enabled in Hyperline ## Setup 1. Go to the [Integrations](https://app.hyperline.co/app/settings/integrations) page in Hyperline 2. Click **Connect** for Stripe 3. Optionally, click **Connect** for Salesforce or HubSpot Please contact our support team after completing the steps above. This process is not self-served and requires a manual operation on our side to enable the Stripe Billing orchestration logic in Hyperline CPQ. ### Import Stripe products catalog Once connected, you can import your Stripe products and coupons catalog into Hyperline. In this setup, Stripe Billing remains the source of truth for configuring your products and coupons. Hyperline automatically replicates and maps all this data to its own concepts and settings (including product and coupon details, price types, variants, tiers, multi-currency setup, etc.). 1. Go to the [Products](https://app.hyperline.co/app/settings/products) page in Hyperline 2. Click **Import from Stripe** on the top right corner 3. Go to the [Coupons](https://app.hyperline.co/app/settings/coupons) page in Hyperline 4. Click **Import from Stripe** on the top right corner You must edit products and coupons in Stripe. Hyperline automatically syncs any changes back. After the initial import, avoid manually reimporting products and coupons using the import buttons. Hyperline automatically replicates all future updates (creation, modification, archival) made in Stripe in real time. Hyperline listens to Stripe webhooks under the hood to keep the data in sync. #### Tax behavior By default, Hyperline only considers products/prices with "exclusive" tax behavior. Hyperline considers all catalog prices as excluding tax and adds taxes at the quote/invoice level (depending on customer details). This means **some Stripe products/prices might not appear in Hyperline** because Hyperline ignores them during import. Use prices excluding taxes by default. If you use other tax behaviors in Stripe (for example, inclusive or unspecified), check with our support team on the best way to handle this. #### Archive products While you can archive or delete products in Stripe, Hyperline also provides a way to archive products directly within the platform. The key difference is that archiving a product in Hyperline does not archive it in Stripe. This allows you to decouple the product status between Stripe (for your internal needs) and Hyperline. A product archived in Hyperline will no longer be visible or available when creating new quotes. 1. Go to the [Products](https://app.hyperline.co/app/settings/products) page in Hyperline 2. Click the product you want to archive 3. Click **Actions** > **Archive** #### Archive prices In addition, following the same logic, you can archive a specific price of a product. The product will still be available when creating new quotes, but the archived price will no longer be suggested. 1. Go to the [Products](https://app.hyperline.co/app/settings/products) page in Hyperline 2. Click the product you want to archive 3. On the related price configuration row, click **Archive** ### Import Stripe customers After importing your products and coupons, Hyperline allows you to import your existing customers. With this action, Hyperline will automatically map Stripe customers within Hyperline, alongside their related payment methods. Hyperline automatically syncs new customers and changes to existing customers in Stripe in real time, including payment methods being added or removed. This action is not available in the interface yet, but you can contact our support team to trigger it for you. The import and the real-time sync attach a Stripe customer to an existing Hyperline customer only in two cases. Either that Hyperline customer is already linked to the Stripe customer ID, or the Stripe customer carries a `hyperlineCustomerId` metadata key holding the Hyperline customer ID. Hyperline does not match customers by name or email address. If a customer already exists in Hyperline (for example, created from your CRM), Hyperline imports it as a second customer. Import your Stripe customers before creating customers from your CRM or manually, and link your CRM records as described in [Reconcile customers between tools](#reconcile-customers-between-tools) before creating quotes. When a Stripe customer has no billing country, Hyperline assigns the country of the invoicing entity. Taxes on future invoices depend on this value, so review imported customers without a country in Stripe and correct them in Stripe. Hyperline applies the change on the next sync. ### Import Stripe subscriptions and invoices Using the same logic as for customers, you can import subscription and invoice histories from Stripe. Hyperline maps all subscription data to Hyperline subscription, phase, subscription product and subscription coupon objects, and invoices to Hyperline invoice and line item objects. Tracking and reporting in Hyperline are available for this data, and you can also query the historical data using the Hyperline API. Hyperline automatically syncs new subscriptions, subscription renewal details, invoice details, statuses, and PDF invoices in real time. ## CRM widget If you've connected your CRM to Hyperline, the CRM widget automatically displays the related customer data (quotes, subscriptions, etc.). As a consequence, you can consult Stripe subscriptions data and invoices in your CRM. [Learn more about reconciling data](#reconcile-customers-between-tools). You can use this widget in both the Account/Company and Opportunity/Deal objects in your CRM. The Contact object is also supported in HubSpot for B2C sales/use cases. In addition to displaying data, the widget allows CRM users to create quotes directly from within the CRM. Hyperline's interfaces are embedded so the full Hyperline experience is available without leaving the CRM. In this context, the CRM's CPQ and product catalog modules are not used. Hyperline delivers the complete CPQ flow and experience, surpassing the limitations, poor user experience, and lack of flexibility of built-in CRM modules, while providing more advanced capabilities and richer integrations. Follow these guides for more details: * [HubSpot card](../../integrations/hubspot.mdx) * [Salesforce component](../../integrations/salesforce.mdx) * [Attio actions](../../integrations/attio.mdx) ### Creating Hyperline customers When the widget loads on CRM pages, Hyperline looks up the related customer using the [reconciliation logic](#in-your-crm) to display the corresponding data. If no match is found, the widget offers to create a new Hyperline customer when the CRM user starts an action (**Create customer**, **Create quote**, **Create subscription**). This creation does not depend on the customer synchronization settings of the integration. To prevent CRM users from creating a new Hyperline customer when no match is found, you can disable the **Allow creating new customer** option under your Hyperline [CRM settings](https://app.hyperline.co/app/settings/integrations). When this option is disabled and no match is found, the widget displays a message (e.g., "*This company has no associated Hyperline customer.*") and no data or actions are available. This is particularly useful to avoid creating duplicates in your billing system. It also ensures that the External ID field in your CRM is populated before displaying the widget, and therefore before any link is created between CRM and Hyperline customers. ## Create a quote Following the setup (only the products import is required), you can start creating quotes directly from your CRM or Hyperline. Follow these guides for more details: * [Create and send quotes](./overview.mdx) * [Quote for subscription update](./subscription-update.mdx) * [Learn about quotes signature](./signature.mdx) * [Configure reusable quote templates](./templates.mdx) Once the quote is signed, Hyperline automatically applies the related changes to the subscriptions in your Stripe account. Some advanced Hyperline quote subscription configurations are not available in this flow. Hyperline ultimately depends on Stripe's subscription capabilities, which can be more limited and less flexible than Hyperline's built-in logic. ### Post-signature automation By default, Hyperline automatically creates or updates the related subscription in Stripe Billing once a quote is signed. This is the recommended behavior, as it keeps both platforms in sync without any manual work. If you'd rather handle the Stripe subscription yourself, you can disable this automation on a per-quote basis. For example, the deal may require a specific Stripe setup that can't be expressed through the quote, or you may plan to update an existing subscription manually. When configuring a quote, open the **Post-signature automation** section and switch off **Orchestrate Stripe Billing after signature**. Once disabled: * After signature, Hyperline does not create or update any subscription in Stripe. * Hyperline displays a notice on the quote to remind your team that the subscription must be set up manually in Stripe. * The rest of the CPQ flow remains unchanged: quote configuration, approval, signature, PDF, and CRM sync all keep working as usual. You can change the toggle at any time before the quote is signed. A permission (Manage quote activation) restricts access to this setting, so you can reserve it for admins or specific roles in your team. ### Quote for subscription update A quote for a subscription update always starts from an existing customer subscription. For subscriptions imported from Stripe into Hyperline, you can select the subscription you want to update to begin creating a quote for update. ## Manage invoices ### Payment terms When configuring a quote or a Hyperline customer, you can set payment terms in days. Hyperline then passes this setting to Stripe when it creates the related subscription. It populates the "days until due" parameter when the collection method is set to "send invoice" (i.e., bank transfer payments). By default, when a card or another automatic payment method is collected on the quote, Hyperline sets the Stripe collection method to "charge automatically". Stripe then charges the customer right away. If you collect a card on quotes but still want to give customers a payment term, our support team can enable the "send invoice" collection method for your account. Hyperline still saves the card and sets it as the default payment method in Stripe. Stripe then sends the invoice with your payment term instead of charging the card automatically. Contact our support team to enable it. ### Purchase order number When configuring a subscription in a quote, you can enter a purchase order (PO) number. Hyperline syncs this number to the Stripe customer invoice settings as a custom field. As a result, Stripe automatically displays it on the invoice PDF header (PO number) when Hyperline creates the subscription. ### Mark as paid You can mark imported unpaid Stripe invoices as paid in Hyperline. On the invoice details page, click **Actions** > **Mark as paid**. The invoice then appears as paid in Hyperline and as paid out of band in Stripe. ## Customer payment methods As previously mentioned, Hyperline imports customer payment methods from Stripe and displays them. You can configure available payment method options in the [Payment](https://app.hyperline.co/app/settings/payment) settings page in Hyperline. These options cover both automated payment methods (card, direct debit, etc.) and bank accounts used for manual bank transfers. You can also collect customer payment methods during the quote signature process. When creating a quote, you can select which payment method types you want your customer to use, and require method collection to sign the quote. Then on the public quote page, your customer can enter their payment method details (card details, direct debit mandate, etc.). Hyperline automatically stores these details in the related Stripe customer, and Stripe Billing then uses them to charge future invoices. ### Bank transfers You can let your customer pay by bank transfer. To make this option available on quotes, first configure a bank account in Hyperline's **Payment** settings and enable it as a payment method. When creating a quote, allow only bank transfers by selecting that bank account in the customer's payment method settings (you can disable all other payment method types). The quote then displays the bank account details directly: * If Stripe supports bank transfers for the customer (based on currency, country, etc.), the quote shows the Stripe virtual bank account number assigned to the customer. * Otherwise, the quote shows the bank account you configured in Hyperline. In this scenario, Hyperline uses Stripe's customer balance mode. The bank account configured in Hyperline acts as the bank transfer payment method and fallback display. When Stripe can generate virtual bank account details for the customer, those Stripe details are displayed on the quote instead. You do not need to enable a separate Stripe virtual IBAN payment method in Hyperline. ## Switch subscriptions to Hyperline At some point, you may want to switch a subscription from Stripe Billing to Hyperline to take advantage of Hyperline's additional capabilities and features for managing the subscription lifecycle. You can do this in a single click: on the subscription details page, click **Actions** > **Switch to Hyperline**. Hyperline also offers the option to cancel the subscription in Stripe at the same time, helping you avoid future double invoicing and duplicate subscriptions between the two platforms. ### Impact on customers This flow has no impact on your end customers. Hyperline imports their payment methods from Stripe Payments, so they don't need to re-enter their card details or create a new direct debit mandate. Subscriptions run in Hyperline with the exact same configuration as in Stripe Billing without service interruption. Hyperline creates and manages new invoices, so the only difference for end customers is the invoice PDF layout. Proceed with this action carefully, and only after fully configuring your Hyperline account, especially the invoicing settings. Once switched, Hyperline will manage and issue all upcoming subscription renewals and invoices, while Stripe will continue to serve as the payment gateway to charge the customer. Don't hesitate to [contact our support team](mailto:support@hyperline.co) for any advice or assistance. ## Reconcile customers between tools Hyperline provides a way to reconcile customers between your CRM, Hyperline, and Stripe. This is useful for ensuring that data is consistent across all tools and for avoiding duplicates. Hyperline links records through identifiers only. It never matches customers by name, email address, or domain. Set up the links described below before your team creates quotes from the CRM and before you enable customer synchronization. Hyperline customers have a dedicated External ID field, which serves as the identifier shared between your CRM and Hyperline. In most cases, this ID corresponds to your internal customer ID. Customers imported from Stripe have an empty External ID: Hyperline stores the Stripe customer ID as a link, not as the External ID. ### In your CRM In your CRM, create a custom field on the Company/Account object: `hyperline_external_id` for HubSpot and Attio, or `HyperlineExternalId__c` for Salesforce. When the widget loads on a record that is not linked yet, Hyperline compares the value of this field, in this order, with: 1. The Hyperline customer ID. 2. The Hyperline customer External ID. 3. The Stripe customer ID of a Hyperline customer already linked to Stripe (for example, a customer imported from Stripe). The comparison is exact and case-sensitive. Make sure this field is populated in your CRM records: * You can leverage workflows to automatically fill this field with data from another field or source in your CRM. You can also have your team input it as part of your internal processes. * If your customers were imported from Stripe, use the Stripe customer ID. It is the only value that matches these customers without further setup. * Otherwise, use your internal customer ID stored as the Hyperline External ID, or the Hyperline customer ID. Hyperline creates the link the first time you interact with the Hyperline widget in the CRM. This requires customer synchronization to be enabled in the integration settings, with a direction that includes CRM to Hyperline. Otherwise, the widget shows the matching customer as a suggestion with a **Link** action. See the [HubSpot](../../integrations/hubspot.mdx#data-reconciliation), [Salesforce](../../integrations/salesforce.mdx#data-reconciliation), and [Attio](../../integrations/attio.mdx#data-reconciliation) pages for the full reconciliation rules. Once you link a CRM entity to a Hyperline customer, the widget uses this link for that entity going forward. This applies regardless of the value in the External ID field. To unlink or change a CRM entity attached to a Hyperline customer, go to the Hyperline customer details page. Click **Edit** under the **Integrations** section and change the CRM entity ID. ### In Stripe Hyperline looks up a Stripe customer from a Hyperline customer only when the two are not linked yet and Hyperline needs to interact with Stripe. This typically happens when Hyperline creates the subscription after a quote is signed. 1. Hyperline looks for a Stripe customer whose ID equals the Hyperline customer's External ID. 2. If none is found, Hyperline looks for a Stripe customer whose `hyperlineExternalId` metadata key equals the Hyperline customer's External ID. Hyperline uses this match only when exactly one Stripe customer carries that value. 3. If none is found, Hyperline creates a new Stripe customer and stores the Hyperline External ID (`hyperlineExternalId`) and the Hyperline customer ID (`hyperlineCustomerId`) in the Stripe customer metadata. Hyperline does not search existing Stripe customers by name or email address. Some existing Stripe customers carry the External ID neither as their ID nor as metadata. To attach one of them, import it (see [Import Stripe customers](#import-stripe-customers)) or link it manually before the quote is signed. To link it manually, go to the Hyperline customer details page and click **Edit** under the **Integrations** section. In the other direction, you can set a `hyperlineCustomerId` metadata key on a Stripe customer. The import and the real-time sync then attach that Stripe customer to the matching Hyperline customer instead of creating a new one. If the Stripe customer has already been imported into Hyperline (e.g., during the initial setup or after a customer was created in Stripe), the Hyperline and Stripe customers are already linked. In that case, Hyperline does not apply any reconciliation logic. ### In Hyperline You can find the actual external ID value on the Hyperline customer details page, under the **Integrations** section. ## Sync custom properties ### Customer custom properties Hyperline also supports syncing customer custom properties from CRM to Stripe, or simply from Hyperline to Stripe. In Hyperline, you can create custom properties for your customers: 1. Go to the [Custom properties](https://app.hyperline.co/app/settings/custom-fields) page in Hyperline 2. Click **Add custom property** 3. Enter a name, a slug, select a type, and select **Customers** as **Enabled entities** If the Company/Account object in the CRM has a custom field with the same slug, Hyperline syncs the value from the CRM to the Hyperline customer custom property. This happens each time Hyperline syncs a customer from the CRM (i.e., when the widget is used in the CRM). Hyperline syncs customer custom properties to Stripe as metadata on the Stripe customer. It uses the custom property slug as the metadata key. ### Subscription custom properties If you create a custom property enabled for the **Subscriptions** entities (using the same process as for customers above), you can set its value when creating a subscription. You can also set it when configuring a subscription as part of a quote, including from the CRM (via the embedded Hyperline UI). When Hyperline creates the subscription in Stripe, it syncs the related custom properties to Stripe as metadata on the Stripe subscription. It uses the custom property slug as the metadata key. ## Dates and timezones Hyperline supports timezone-specific settings per customer, while Stripe operates exclusively in UTC. This difference can cause dates to appear shifted by one day in Stripe. For example, a customer's timezone is set to `Europe/Paris` and a subscription is configured to start on **April 1**. Hyperline represents this as **March 31 at 22:00 UTC** (during summer time, UTC+2). Since Stripe only works with UTC dates without timezone information, the subscription start date in Stripe will appear as **March 31** instead of April 1. This is expected behavior and does not affect billing accuracy. The subscription will still start at the correct local time for the customer. The same logic applies to all date-based fields synced to Stripe (subscription start dates, phase transitions, etc.). If date alignment in Stripe is important for your reporting or internal processes, set all your customers' timezone to UTC in Hyperline. This ensures that dates in Hyperline and Stripe always match. Otherwise, customers with timezones ahead of UTC (e.g., Europe, Asia) may see dates shifted one day earlier in Stripe. ## Connect multiple Stripe accounts Hyperline allows you to connect multiple Stripe Billing accounts to a single Hyperline account. This is useful for organizations operating in multiple regions or managing different business units with separate Stripe accounts. In this setup, you can import products and coupons from multiple Stripe accounts into your Hyperline product catalog. Each Hyperline customer can be linked to a specific Stripe account (i.e., a single Hyperline customer may be associated with multiple Stripe accounts). When creating a quote, Hyperline filters the list of available products and coupons based on the first product you select when creating the quote. This first selected product determines which Stripe account will be used for the quote and for creating the subscription. ## Technical details ### Stripe subscription orchestration When a quote is signed, Hyperline automatically orchestrates the creation of subscriptions in Stripe Billing. Depending on the context, Hyperline creates either a Stripe **subscription** or a **subscription schedule** (e.g., when the subscription includes future phases or scheduled changes). Hyperline creates all Stripe subscriptions in flexible mode to ensure compatibility with Stripe's newest capabilities and features. This orchestration is fully automated, so no manual intervention is required. Hyperline handles the mapping of products, prices, coupons, and phases to their Stripe equivalents. ### Look up Hyperline IDs from Stripe When Hyperline creates a subscription in Stripe, it automatically adds custom metadata fields to the corresponding Stripe subscription object: * `hyperlineSubscriptionId`: The Hyperline subscription ID, stored on the Stripe subscription. * `hyperlinePhaseId`: The Hyperline phase ID, stored on the Stripe subscription. * `hyperlineProductId`: The Hyperline product ID, stored on the Stripe subscription product. You can use these metadata values to look up the related Hyperline entities from a Stripe subscription using the Hyperline API. # Quote for subscription update Source: https://docs.hyperline.co/docs/quotes/subscription-update Generate a Hyperline quote to update an active subscription with customer approval, ideal for contract upsells, add-ons, and price changes. If a subscription is already active in Hyperline, you can update it with customer approval by requiring a signed quote before applying changes. This is ideal for contract upsells, adding products, or adjusting prices and quantities. ## Create a quote for subscription update To create a quote to update a subscription, the subscription must be in `active` state. You can have several open quotes for subscription update on the same subscription at once. For example, you can negotiate multiple upsell scenarios in parallel or prepare a follow-up change while a first quote is still awaiting signature. There are two ways to create a quote for subscription update: * from the **quotes** page, click **new quote** and select **quote for subscription update**, then select the customer and the subscription you want to update. * from the **subscription details** page, click **actions** and select **create update quote**. All open quotes for subscription update on a subscription are listed on the **quotes** tab of the subscription details page. You can review, edit, or void any of them at a glance. ### Select update effective date When you start the update process, you can select one of two options for when the update takes effect. Quote Update First Step **On quote signature** Hyperline sets the subscription start date to `quote signature`, so the new version of this subscription only applies once the customer signs the quote. **On selected date** You can select any future date as the subscription start date. Once the quote is signed, the new subscription will be in a pending state, and will automatically replace the previous one on the selected date. If the selected date has passed once the quote is signed, the subscription will automatically be activated on quote signature. #### Expiration date for scheduled updates When the update is scheduled on a selected date, Hyperline caps the quote expiration date so it cannot extend past the planned transition. The latest allowed expiration is: * the **end of the current billing period** when the transition date falls within it * the **transition date** itself when it falls after the current billing period If a scheduled subscription-update quote reaches its expiration date before being signed, Hyperline automatically voids it and cancels the pending transition. The voided quote remains visible in the quotes list for auditability, and the source subscription continues unchanged. Invoicing continues normally on its existing schedule. ### Keep current configuration or start from an existing template You can decide to update the current subscription configuration, which is ideal for adding products, coupons, phases and editing transition dates. You can also start from an existing template, which is ideal for pre-configured upsells and downsells. Keep Configuration Select Template ### Configure your subscription Just like when creating a subscription, you can now freely edit its new configuration. * Contract * Subscription configuration * Invoicing settings * Custom properties ### Select the transition settings Decide how Hyperline handles the transition between the two subscriptions, like when [updating a subscription](/api-reference/endpoints/subscriptions/update-subscription). You can change this configuration on the quote configuration page by clicking **revise transition**. Subscription Update Configure Transition Select whether you'd like to keep the current billing cycle or start a new one, and generate a transition invoice or not. ### Configure your quote To ensure accuracy, Hyperline highlights all subscription changes, including added or removed products, price and quantity updates, and any phase modifications. Quote Update Details Then, the process is the same as for a [new quote](./overview). In the display settings, use the **Subscription update details** dropdown to select what appears on the quote and its PDF: | Option | What the quote shows | | - | - | | **Quote update details** | Only the changes to the subscription, including update and proration details. This is the default. | | **Subscription details** | Only the newly configured subscription. Update and proration details are hidden. | | **Both** | The changes to the subscription, followed by the full newly configured subscription. | You can set this option on each quote, as a default in your quoting settings, and in [quote templates](./templates). ### Send quote Once the quote is finalized, it will turn to the `ready to send` status. Review the quote configuration and decide to send it via email or generate a public link and send it by yourself. Note that if you use the latter, Hyperline will not track email reception and openings. ### Pending signature Once the quote has been sent, it will turn to the `pending signature` status. At this stage, you can edit the quote again. Note that editing turns it back to the `draft` status. The customer can't access the link until you save it and make it live again by clicking **generate public link**. Quote Pending Update While a quote for subscription update is pending signature, you cannot edit the source subscription directly, but you can still create additional update quotes on it. All open update quotes are visible on the **quotes** tab of the subscription details page. ### Quote signed Once the quote is signed, the subscription is executed or pending the selected date. The new version overrides the previous version of the subscription, and Hyperline automatically applies the changes. # Quote templates Source: https://docs.hyperline.co/docs/quotes/templates Speed up the Hyperline quoting process with reusable quote templates that pre-fill products, pricing, terms, and clauses for sales teams. To simplify the quote creation process, Hyperline offers a feature to create templates, allowing you to pre-configure a quote for it to be sent in a few clicks. As with any other concept in Hyperline, you can override values entered in the quote template after selecting the template in the quote creation process. Editing a quote template will not impact the draft quotes created using this template. ## Creating a template Quote templates are nested under the `quoting` folder, on the `templates` page. Add a name and optionally an internal description to make it easily identifiable for your sales team. Pre-configure the expiration delay and information required from customers to sign the quote. Quote templates can contain a pre-configured subscription template. This will generate a subscription filled with the contract, products and price configurations, coupons and invoicing settings based on the customers' country and currency. You can override this pre-filled information while creating the quote. More details in the [subscription templates page](../subscriptions/templates). You can add a note for the customer and contract terms, that can be pre-filled with clauses configured in **Settings > Quoting**. When sending a quote to a customer, you might want to attach a contract or your terms and conditions so they can sign both the quote and the contract simultaneously. Attachments can be: * **Added manually** on the template * **Added dynamically** based on the customers' country and language through localized attachments configured in **Settings > Quoting**. ## Using a template When creating a quote, you can select a pre-configured template or start with an empty quote by selecting `configure manually`. ## Localized attachments If your team frequently sends quotes with the same contract details, manually attaching files can become time-consuming, especially for sales teams that may struggle to select the right templates. With localized attachments, you can configure attachments to be automatically added based on the invoicing entity, country and language of the customer. Give it a descriptive name and select the invoicing entities eligible (attachments will only be available for customers linked to selected entities). Click `new file` and select the language and country. You can add up to **10 documents** per entry, select multiple files at once from the picker, and drag them to reorder. When you use a quote template with this localized attachment, Hyperline automatically attaches the documents to quotes for customers matching these criteria, in the order defined here. Each document must be in one of the following formats: `PDF`, `DOC`, `DOCX`, `PPT`, `PPTX`, or `TXT`, with a maximum size of 5 MB per file. With your localized attachment now configured, you can add it to your quote templates. Hyperline then automatically adds the attachments to quotes created using the template. ## Clauses Clauses are a lighter version of localized attachments that allows you to add dynamic text based on the invoicing entity and customer's language in the `contract terms` text field. You need the **Contracts read** permission to view and use contract clauses in the quote editor. Without this permission, the clause insertion options will not be available. Learn more about [user roles and permissions](../account/users-permissions#manage-roles). Give it a descriptive name and select the invoicing entities eligible (clauses will only be available for customers linked to selected entities). Enter content in the text area. You can add alternative versions for different languages by clicking the **blue globe icon**. If you don't set translations, Hyperline adds the default version. After configuring the clause, you can add it to your quote templates. When you create a quote using the template, Hyperline automatically pre-fills the clause content in the contract terms field in the customer's language. You can also add a clause while creating or editing a quote from **Contract terms** by selecting **Add from existing clause**. Selecting an added clause again removes the clause text when the original text is still present. If you edit the inserted text, Hyperline keeps the quote linked to the selected clause and can identify it as a modified clause for [approval workflows](./approval). This lets you route quotes for review when standard legal language changes. ## Links and legal terms Quote notes and contract terms support Markdown formatting. To add a clickable legal link, write the label in brackets and the URL in parentheses: ```mdx theme={null} [General terms and conditions](https://www.example.com/legal/terms) ``` This displays a readable link label on the quote instead of the full URL. For more formatting options, see [Markdown text](../account/settings#markdown-text). You can configure legal terms in two places: * **Settings** > **Quoting**, where you manage reusable clauses and default quote terms. * Quote templates, where you pre-fill the terms used by quotes created from that template. You configure hosted checkout legal terms separately from quote templates. Keep both settings aligned if customers can sign through either flow. # Sentinel monitoring Source: https://docs.hyperline.co/docs/sentinel/overview Monitor Hyperline billing operations with Sentinel: actionable tasks for failed payments, disconnected integrations, and other revenue issues. Sentinel is Hyperline's built-in monitoring system. It continuously watches your billing operations and surfaces actionable alerts, called **tasks**, whenever something needs your attention, from failed payments to disconnected integrations. The Sentinel panel is available only to users with the **View tasks** role. Within the panel, each user only sees the tasks and entities they have permission to access, based on their role. ## How it works Sentinel runs in the background and creates a task whenever it detects an issue in one of the monitored areas (payments, invoicing, subscriptions, quotes, or integrations). Tasks are deduplicated so you see a single rolled-up alert per issue category, with a count of affected entities. Each task includes a short description, the number of affected entities (invoices, customers, subscriptions, etc.), and a link to the relevant list page. Use the link to drill down and resolve the issue. You can filter the list using the **All**, **Critical**, **High**, and **Moderate** tabs to focus on the most pressing issues first. ### Refreshing tasks When you take an action that resolves part of a task, the task count and list of affected entities refresh automatically a few seconds later. If the count still looks out of date, you can trigger a manual refresh directly on the task. ## Monitored alerts Sentinel monitors the following alerts, grouped by category: ### Payments | Alert | Description | | - | - | | Invoice in error | A payment attempt on an invoice has failed. | | Customer with expired payment method | The saved payment method has expired. | | Customer with payment method expiring soon | The saved payment method is about to expire. | | Payment method from a different invoicing entity | The customer's payment method belongs to a different invoicing entity than the one issuing the invoice. | | Payment provider disconnected | A payment provider connection is no longer authorized. | | Bank account failed to sync | Hyperline could not refresh transactions from a connected bank account. | ### Invoicing | Alert | Description | | - | - | | Invoice is late | An invoice has passed its due date without being paid. | | Invoice draft | A draft invoice is waiting to be finalized. | | Electronic invoice failed to sync | An electronic invoice could not be delivered to the tax authority. | | Customer has invalid tax ID | The tax ID on the customer record failed validation, for example because it is `invalid` or does not match the customer's country. | | Child invoice can't be grouped onto parent | A child invoice in a `Grouped` organisation-based billing setup can't be rolled up onto its parent because its invoicing entity differs from the parent's. | ### Quotes | Alert | Description | | - | - | | Quote activation failed | A quote was accepted but could not be turned into a subscription. | ### Subscriptions | Alert | Description | | - | - | | Subscription is errored | The subscription is in an error state and is not billing as expected. | | Subscription renewal failed | Automatic renewal of a subscription did not complete. | ### Integrations | Alert | Description | | - | - | | Integration disconnected | A third-party integration lost its authorization. | | Integration setup error | A newly added integration could not finish setup. | | Integration needs reconfiguration | An existing integration requires updated credentials or settings. | | Issue with integration | The integration sync produced an error. | | Data loader failed to sync | A usage data loader could not refresh data. | ## Settings Open the Sentinel settings to control which alerts are surfaced. You can enable or disable each alert individually. This is useful for issues that don't apply to your setup. For example, you can hide electronic invoice alerts if you don't issue them. Disabled alerts won't be created or shown in your task list. # Checkout page Source: https://docs.hyperline.co/docs/subscriptions/checkout-page Create hosted Hyperline checkout sessions where customers review pricing, enter billing details, and pay securely across multiple payment methods. When assigning a subscription or processing a one-time payment, Hyperline allows you to create a **checkout session**. This generates a shareable public page where customers can review payment details, enter billing information, select a payment method, and complete their purchase. Hyperline’s checkout pages are optimized for seamless payments and support multiple methods, including credit cards, direct debits, and bank transfers. ## Create checkout Checkout completion can serve as a **subscription** or **one-time payment** trigger, automatically generating the first invoice once completed. You can also set subscriptions to begin on a future date or require manual activation. In either case, the customer still needs to fill in their information via the checkout. When assigning the subscription, you can decide whether to generate a checkout session in the payment settings (step 2). You can **send the checkout link by email** to share it directly with your customer. By default, the email field is pre-filled with the customer’s email address, but you can customize it as needed. Once assigned, the subscription will be pending checkout completion. A customer can have multiple checkout links at the same time, for several subscriptions and one-time payments. You can find all of them at the top right of the customer page. ## Checkout lifecycle A checkout session remains available until it is completed, cancelled, or errored. Checkout sessions do not expire automatically after a fixed duration. | Status | Meaning | | - | - | | `opened` | The checkout link has been created and the customer can still complete it. | | `completed` | The customer completed checkout and the related subscription or payment can continue. | | `cancelled` | The checkout session was cancelled and the link should no longer be used. | | `errored` | Checkout could not be completed because an error occurred. | Because checkout sessions do not auto-expire, there is no `checkout.expired` webhook event. Use `checkout.completed` to detect successful completion, and cancel the checkout from Hyperline if the link should no longer be usable. ## Complete checkout Once on the checkout page, the customer can review their subscription details and enter their billing information. They then enter their payment details, based on the **allowed payment methods** configured on their Hyperline page. You can enable credit card, direct debit, bank transfer, or any combination of these options. ## Require a tax identifier at checkout If your billing process requires a tax identifier, go to **Settings** > **Taxes** for the relevant invoicing entity and enable **Require customer tax identifier** before sending the checkout link. When enabled, company customers must enter a Tax ID before they can complete checkout. To accept a country-specific tax number instead, also enable **Enable local tax number**. Company customers can then complete checkout with either a Tax ID or a local tax number. Use these settings when a customer tax identifier is required for compliant invoicing, reverse charge handling, or internal approval. Tax ID validation and reverse charge enforcement remain based on the Tax ID. See [Tax enforcement options](../invoices/tax-management#tax-enforcement-options) for details. Once the customer completes the checkout, they receive a confirmation email verifying that their payment has been successfully processed. You can disable **Checkout session created** and **Checkout session completed** in **Settings** > **Emailing** > **Customer emails**. See [Email settings](../account/emails) to configure your sender and preview these templates. ## Checkout with a payment initiation delay If a [payment initiation delay](../invoices/term#payment-initiation-delay) applies to the customer, Hyperline doesn't charge the checkout invoice right away. Hyperline schedules the payment on the invoice for the end of the delay instead. Hyperline activates the subscription as soon as the customer completes the checkout, without waiting for the payment to succeed. # Automated seat-based billing Source: https://docs.hyperline.co/docs/subscriptions/connected-seats Automate seat-based billing in Hyperline by syncing seat counts directly from your database in real time as users, licenses, or units change. ## Concept Connected seats are an improvement over the existing [seat](/docs/products/overview#seat) product. Instead of manually entering the number of units when initiating a subscription, this data is fetched directly from your database. This is especially useful if: * You want your billing system to reflect any changes made to your product (e.g. a user adds a new license) * You want to keep track of which seat was added or removed, and when * You want to bill prorated amounts (e.g. a customer starts with 5 licenses but adds another one mid-year) ## Practical application ### How to create an automated seat-based product? Navigate to the **Products** section. Select an existing **count** [aggregator](/docs/usage/aggregators) to track your seats. The aggregator determines which events are counted and how incoming data is factored into billing calculations. If you haven't created one yet, head to **Usage > Aggregators** to set one up first. That's it! Your seat-based product should now be marked as "**Connected seat**". ### How to configure a connected seats product in subscriptions? There are four configuration parameters: **Refresh schedule**, **Charging method**, **Invoicing schedule**, and **Seat change policy**. #### Refresh schedule * **Realtime**: The `count` updates immediately when a change is detected, instantly if you're using the API, or based on the dataloader interval if you're using loaders. * **Periodic**: The `count` refreshes based on the interval you enter in the **Refresh interval** field. It's independent of the subscription billing interval but can be matched to it. * **Manual**: You must trigger the refresh using the endpoint for a more customized experience. #### Charging method Determines how Hyperline bills seat changes it detects during the period. * **Do not charge**: Track seat counts without generating charges. * **Prorata**: Charge proportionally based on when the change occurred in the period. * **Full amount**: Charge the full period price regardless of when the change occurred. #### Invoicing schedule Controls when Hyperline generates invoices after it detects seat changes. This setting is only available when the charging method is not set to “Do not charge”. * **Immediately**: Hyperline charges (or refunds) the update as soon as it detects it, even in the middle of the period. If selected alongside the “periodic” option, it will simply invoice the customer at every “end” of period. * **With next invoice**: Hyperline adds the update amounts to the next invoice as additional lines. For example, if the update is realtime but invoicing is at the end of the month, Hyperline updates the subscription count in realtime and adds the charge to the next invoice. * **Custom**: Lets you set an invoicing period. For instance, use it if you have an annual subscription you want to update in realtime but want to charge every month. #### Seat change policy Determines how increases or decreases in seat count affect billing during the period. This setting is only available when the charging method is not set to “Do not charge”. * **Standard**: No special handling for seat changes during the period. * **Charge highest**: Always bill based on the highest seat count detected during the period. Useful to always commit the maximum number of seats. * **Refund decrease**: Issue a refund when the seat count decreases. Instructs Hyperline to count negative updates as refunds if they've already been paid. ### Managing seat decreases When a seat is removed (e.g., a user is deleted or a license is revoked), you need to signal this change to Hyperline. Since the API is append-only, you don't delete events directly. Instead, you update them with a flag and configure the aggregator to filter them out. **Using an `active` or `archived` (or what you want) boolean:** Use a boolean flag to mark the seat as inactive: ```json theme={null} { "customer_id": "", "timestamp": "2024-03-15T10:00:00.000Z", "event_type": "users", "record": { "id": 258, "email": "user@company.com", "created_at": "2024-01-01T00:00:00.000Z", "archived": true } } ``` Then, configure the product's [aggregator](/docs/usage/aggregators) to filter out archived seats: * For a boolean field: add a filter where `archived` **equals** `false` ## Billing calculation examples Understanding how Hyperline calculates billing adjustments when seat counts change is essential for predicting your invoices. This section walks through concrete examples using a base price of **10€ per seat** with a monthly subscription running from the 1st to the 30th. Those examples do not take into account the settings: `Refund when a decrease in unit count is detected` and `Charge the highest detected value for the period`. ### End of period billing When your subscription is configured to bill at the end of the period, Hyperline calculates the final seat count and applies adjustments for any mid-period changes. With pro-rata billing, adjustments are calculated proportionally based on when the change occurred during the billing period. **Adding seats (60 → 100 seats)** You start the month with 60 seats and add 40 seats on the 15th. | Item | Calculation | Amount | | - | - | - | | Base charge | 10€ × 100 seats | 1,000€ | | Update adjustment (Jan 1–15) | -40 × 10€ × 15d/30d | -200€ | | **Total** | | **800€** | The adjustment credits back the 40 seats for the first half of the month when they weren't in use. **Removing seats (100 → 60 seats)** You start the month with 100 seats and remove 40 seats on the 15th. | Item | Calculation | Amount | | - | - | - | | Base charge | 10€ × 60 seats | 600€ | | Update adjustment (Jan 1–15) | 40 × 10€ × 15d/30d | +200€ | | **Total** | | **800€** | The adjustment charges for the 40 seats that were used during the first half of the month. With pay in full billing, seat additions are charged at full price regardless of when they were added, while removals still account for usage during the period. **Adding seats (60 → 100 seats)** You start the month with 60 seats and add 40 seats on the 15th. | Item | Calculation | Amount | | - | - | - | | Base charge | 10€ × 100 seats | 1,000€ | | Update adjustment | — | 0€ | | **Total** | | **1,000€** | New seats are charged at full price for the entire period, regardless of when they were added. **Removing seats (100 → 60 seats)** You start the month with 100 seats and remove 40 seats on the 15th. | Item | Calculation | Amount | | - | - | - | | Base charge | 10€ × 60 seats | 600€ | | Update adjustment | 40 × 10€ | +400€ | | **Total** | | **1,000€** | Removed seats are still charged at full price for the period they were active. When configured to not charge for updates, no adjustment line items are generated. * **Adding seats:** No additional charge (0€) * **Removing seats:** No refund or adjustment (0€) ### Start of period billing When your subscription is configured to bill at the start of the period, you pay upfront based on your current seat count. Adjustments for mid-period changes are applied on the following invoice. With pro-rata billing, adjustments are calculated proportionally and applied to the next invoice. **Adding seats (60 → 100 seats)** You start January with 60 seats and add 40 seats on the 15th. *Invoice on 1st January (for January period):* | Item | Calculation | Amount | | - | - | - | | Base charge | 10€ × 60 seats | 600€ | | **Total** | | **600€** | *Invoice on 1st February (for February period):* | Item | Calculation | Amount | | - | - | - | | Base charge | 10€ × 100 seats | 1,000€ | | Update adjustment (Jan 15–30) | 40 × 10€ × 15d/30d | +200€ | | **Total** | | **1,200€** | **Total for January + February: 1,800€**\ The February invoice includes the pro-rated charge for the 40 seats added mid-January. **Removing seats (100 → 60 seats)** You start January with 100 seats and remove 40 seats on the 15th. *Invoice on 1st January (for January period):* | Item | Calculation | Amount | | - | - | - | | Base charge | 10€ × 100 seats | 1,000€ | | **Total** | | **1,000€** | *Invoice on 1st February (for February period):* | Item | Calculation | Amount | | - | - | - | | Base charge | 10€ × 60 seats | 600€ | | Update adjustment (Jan 15–30) | -40 × 10€ × 15d/30d | -200€ | | **Total** | | **400€** | **Total for January + February: 1,400€** The February invoice includes a credit for the 40 seats removed mid-January. With pay in full billing, seat changes trigger full-price adjustments on the next invoice. **Adding seats (60 → 100 seats)** You start January with 60 seats and add 40 seats on the 15th. *Invoice on 1st January (for January period):* | Item | Calculation | Amount | | - | - | - | | Base charge | 10€ × 60 seats | 600€ | | **Total** | | **600€** | *Invoice on 1st February (for February period):* | Item | Calculation | Amount | | - | - | - | | Base charge | 10€ × 100 seats | 1,000€ | | Update adjustment (full Jan) | 40 × 10€ | +400€ | | **Total** | | **1,400€** | **Total for January + February: 2,000€** The added seats are charged at full price for the previous period. **Removing seats (100 → 60 seats)** You start January with 100 seats and remove 40 seats on the 15th. *Invoice on 1st January (for January period):* | Item | Calculation | Amount | | - | - | - | | Base charge | 10€ × 100 seats | 1,000€ | | **Total** | | **1,000€** | *Invoice on 1st February (for February period):* | Item | Calculation | Amount | | - | - | - | | Base charge | 10€ × 60 seats | 600€ | | **Total** | | **600€** | **Total for January + February: 1,600€** A refund is applied for the removed seats from the previous period. When configured to not charge for updates, no adjustment line items are generated. * **Adding seats:** No additional charge (0€) * **Removing seats:** No refund or adjustment (0€) ## Explore consumption In the context of connected seats, consumption refers to the usage of the seat-based product. You can review this consumption in the dedicated section within the Hyperline platform. This view provides a comprehensive look at the usage of each seat-based product, allowing for better understanding and management of your billing process. You can also review the consumption of a subscription in the subscription timeline. You can find more detailed information in the [Explore usage consumption section](/docs/usage/explore-usage-consumption). # Contract Source: https://docs.hyperline.co/docs/subscriptions/contracts Configure subscription contract dates, automatic renewals, and price adjustments at renewal or at a separate interval. A contract defines the agreed term between you and your customer. Its duration is separate from the subscription's billing cycle: an annual contract can, for example, be billed monthly. You can also use the contract start date to start the subscription and configure price adjustments at contract renewal or at a separate interval. ## Configure a contract 1. When [creating a subscription](./create), enable the toggle in the **Contract** section. 2. Select when the contract starts and ends using the options below. 3. If the contract has a defined end, select whether it renews automatically and set the renewal duration. Save contract settings in a [subscription template](./templates) to reuse them when creating subscriptions. You can customize the settings for each customer. ### Start date | Option | When the contract starts | | - | - | | **Immediately** | When you assign the subscription. | | **Checkout completion** | When your customer completes checkout, when this option is available in the creation flow. | | **Quote signature** | When your customer signs the quote, when creating a subscription through a quote. | | **Manual start** | When you manually start the contract after assigning the subscription. | | **Custom date** | On a date you choose, in the past or future. | If you select **Contract start date** as the subscription's start option, the contract start date determines when the subscription starts. It also determines the initial billing date if billing is configured to start with the subscription. ### End date and automatic renewal | Option | When the contract ends | | - | - | | **After a relative duration** | After a duration measured from the contract start, such as six months or one year. | | **Forever** | No scheduled end date. The contract can end manually or when the subscription ends. | | **Custom date** | On a date you choose. | For a relative duration or a custom end date, enable **Renew contract automatically at the end of the duration** to renew the contract for the duration you specify. The renewal duration can differ from the initial contract duration. For example, a three-year contract with a one-year renewal duration first renews after three years, then every year. You configure contract dates and subscription dates separately. Ending a contract does not by itself cancel the subscription. When the subscription ends, Hyperline marks its associated contract as finished. ## Contract status | Status | Meaning | | - | - | | `inactive` | The contract has not started. | | `active` | The contract has started and has not ended. | | `finished` | The contract has ended. | ## Update a contract Open the subscription and use **Update subscription** in the **Contract** section to add or edit its contract settings. You can also remove the contract through the [subscription update flow](./update#contract). For an active contract, you edit the start date as a specific date. The end date cannot be earlier than the contract start date. Subscription update availability also depends on the subscription's state; see [subscription update restrictions](./update). ## Price adjustments Apply a percentage adjustment to recurring product prices at each contract renewal or at a separate interval during the contract. For tailored changes by phase or product, use [dedicated subscription phases](#configure-adjustments-by-phase-or-product). Set a contract duration or a custom end date, then turn on **Price adjustment** in the contract settings. For an existing subscription, open **Update** in the **Contract** section. 1. Enter the **Adjustment percentage**. Positive values increase prices; negative values decrease them. The minimum is −100%. 2. Select an **Adjustment frequency**: * **At each renewal**: apply the adjustment at the end of the initial contract term, then at each contract renewal. You must enable automatic contract renewal. * **Duration**: use **Every** to enter a count and unit, such as **1 year** or **6 months**. The schedule starts from the contract start date and works even if automatic contract renewal is disabled. 3. Select an **Application** option from the table below. 4. For a quote or draft update, set **Days before adjustment** to prepare it in advance. This controls preparation, not when the new prices take effect. 5. Select whether to **Prorate price adjustment**. | Application | What happens | | - | - | | **Apply automatically** | Applies the configured adjustment on its scheduled date without preparing a quote for signature or a draft for review. | | **Create quote update** | Prepares a draft [quote for subscription update](../quotes/subscription-update). Edit and finalize it through the usual quote flow. The change requires quote signature before it can apply. | | **Create draft update** | Prepares an editable [advanced subscription update](./update#advanced-update) in **Versions**. Review and submit it through the usual update flow before it can apply. | Preparing a quote or draft does not apply the proposed prices. The contract can still renew while the proposal awaits signature or submission. Existing renewal-based adjustments keep **At each renewal** as their frequency. Disabling automatic contract renewal removes an **At each renewal** adjustment; a **Duration** adjustment remains configured and stops when the contract ends. ### Choose when the first adjustment applies Contract duration, renewal duration, billing frequency, and adjustment frequency control different dates: | Setting | Example | What it controls | | - | - | - | | Contract duration | 3 years | The initial commitment. | | Renewal duration | 1 year | The length of each new contract term after the initial commitment ends. | | Billing frequency | Monthly | The periods you invoice. | | Adjustment frequency | Every 1 year | How often the percentage applies, starting from the contract start date. | With **Duration** set to **1 year**, the first adjustment applies after one full year, then every year. It does not apply immediately or on every monthly invoice. With **At each renewal**, a three-year contract receives its first adjustment after three years. If you enable or change a duration schedule after the contract starts, Hyperline uses the next scheduled date after your change. It does not apply missed increases retroactively. If the contract does not renew, no adjustment applies at its final end date. ### How prices change The percentage applies to current recurring prices before discounts, so successive applied adjustments compound. It excludes credit products, one-off charges, and products billed only once, and does not change product quantities or tier boundaries. The adjustment updates the subscription's prices without changing catalog prices. For percentage-based product pricing, the adjustment is relative: +10% changes a 1% rate to 1.1%, not 11%. Hyperline also adjusts associated caps, floors, and fees. Your customer has a three-year contract starting October 5, 2026, and pays €200 per month before taxes and discounts, billed in advance on the 5th. You select **Duration**, **Every 1 year**, **+1.3%**, and **Apply automatically**. | Monthly periods starting | Price displayed | | - | - | | October 5, 2026 through September 5, 2027 | €200.00 | | October 5, 2027 through September 5, 2028 | €202.60 | | October 5, 2028 through September 5, 2029 | €205.23 | The second increase applies to €202.60, with the result rounded for display. These annual increases apply during the initial commitment, even when automatic contract renewal is off. ### Check upcoming prices in the timeline Open the subscription's **Timeline** and check the invoice amounts under **Upcoming events**. A **Subscription renewal** event can represent a new billing period without renewing the contract term. The timeline initially shows only a limited number of events. Use **Load more events** to reach the first adjustment date. In the example above, invoices through April 2027 should still show €200; load events through October 2027 to see €202.60. For an automatic adjustment that aligns with billing, check the invoice amount or **Preview**. A separate quote or subscription update event is not required. ### Configure adjustments by phase or product The contract-level percentage applies to eligible recurring products together. To give individual products different increases, keep selected prices unchanged, or schedule a specific pricing change, create a dedicated [subscription phase](./phases). 1. In the subscription configuration, select **Duplicate phase** to copy the existing products and prices into a new phase. For a live subscription, open [**Update subscription**](./update#global-update) first. 2. Set the preceding phase to end so the new phase starts on the agreed pricing change date. Each phase starts when the previous one ends. 3. In the new phase, enter the agreed prices for the products you want to adjust. Keep the other products at their existing prices. 4. Review the [phase transition](./phases#phase-transition) and billing settings before saving. Add further phases for additional agreed pricing changes. Use the prices configured in each phase for this approach. Leave **Price adjustment** off when only selected products should change, so a contract-wide percentage does not also apply. Your customer pays €1,000 per month for a platform subscription and €200 per month for support. At the annual renewal, only the platform price increases by 3%. Duplicate the phase, set the platform price to €1,030, and keep support at €200. Schedule the new phase to start on the agreed renewal date. ### Apply a Syntec-based adjustment For contracts that reference the Syntec index, enter the applicable percentage manually in **Adjustment percentage**. You control the rate used for each adjustment; Hyperline applies the percentage you enter through your chosen **Application** workflow. 1. Determine the percentage for the upcoming adjustment using the Syntec reference values and calculation agreed in your customer's contract. 2. Open **Update** in the **Contract** section and enter that percentage in **Adjustment percentage**. For example, if the agreed calculation gives a 2.5% increase, enter **2.5**. 3. Save the percentage before the adjustment date, or before the preparation date if you use **Create quote update** or **Create draft update**. Review any proposal already prepared before finalizing it. 4. Review and update the percentage for each subsequent adjustment using the applicable index values. The saved percentage remains in use until you change it. Select **Create quote update** or **Create draft update** when you want to review the proposed prices before they apply. If the Syntec adjustment concerns only selected products, use a dedicated phase and enter their revised prices as described above. ### Adjustment and billing dates When an adjustment falls on a billing boundary, the new period uses the adjusted price. An invoice issued at the start of that period reflects the increase; an invoice billing the period just ended in arrears retains that period's price. If the adjustment falls between billing dates: * With **Prorate price adjustment** off, the period already started keeps its original price. The new price applies from the next billing period. * With it on, the price change takes effect on the adjustment date, with a prorated adjustment for the remainder of the current billing period. Hyperline keeps the existing billing cycle. For quote and draft modes, these settings prepare the proposal; application still follows the normal quote or subscription update workflow. ## Related guides * [Create a subscription](./create) * [Update a subscription](./update) * [Create a quote for a subscription update](../quotes/subscription-update) * [Configure subscription templates](./templates) # Create a subscription Source: https://docs.hyperline.co/docs/subscriptions/create Assign subscriptions to customers in Hyperline manually or via templates, with options for trials, contracts, billing cycles, and activation strategies. Creating subscriptions is a central capability in Hyperline. This article covers the various options available to assign them to your customers, from simple to more complex needs. Before starting a subscription, you must [configure the products](../products/overview) you wish to bill. Optionally, you can create [templates](../subscriptions/templates) to streamline the subscription assignment process with reusable package configurations. Though products are configured at the account level, you can customize every option at the customer level. This lets you adjust them according to specific needs on a per-case basis without impacting your overall configuration. ## Configure a subscription Configuring a subscription in Hyperline only takes a few clicks. However, you can also customize subscriptions on a per-customer basis for greater versatility and agility. You can also create new subscriptions from the subscription list page. In this case, you also need to select the customer. You can start a subscription either from a [pre-configured template](./templates) or configure your subscription manually from scratch. **Subscription start** * **In the past**, if you want to backport a subscription that has already started but not in Hyperline, or you want to bill a customer in arrears. Hyperline bills any past period that's due. * **Immediately**, the default value * **In the future**, if you want to schedule a subscription for the future * **On checkout completion**, once your customer completes the checkout **Subscription alignment** Subscriptions follow a predictable renewal pattern based on their start date: * If a subscription begins at the standard start of a billing period (e.g., the 1st of the month for monthly plans or the 1st of the year for annual plans), it aligns automatically. Each new period then starts on the same fixed date. * If a subscription starts on any other day, it renews on the same calendar day in the next period. For example, a monthly subscription starting on March 15th renews on April 15th. In the contract configuration, you can configure a **contract duration** by activating the toggle. Contract duration replaces the notion of **commitment** that has been deprecated. See [contracts](../subscriptions/contracts) for more information. When adding products outside of a template, after you select the product, Hyperline displays the list of prices set in your product catalog. It's divided into a few sections: * **Suggested:** lists the best pricing according to various parameters of the subscription: The customer's country, their currency, the commitment duration. * **Others:** lists the rest of the prices available for the product. * **Manual configuration:** If no matches are found or you don't find the right price, you can select "Manual configuration". In the next step, you can enter the price and frequency yourself. Once you select the pricing configuration, you can edit the product details. Editing a product configuration **does not impact your catalog** and only affects the subscription you're currently creating. This gives you the flexibility to set customer-specific pricing. You can adjust the quantity directly from the main subscription view, making it easy to customize a subscription especially when starting from a pre-configured template. You can also assign [coupons](../coupons/overview) to your subscription. These coupons can be a fixed amount in the customer's currency, or a percentage of the product price. They can apply to specific or all products. After you select a coupon, you can set: * The **application date**: select whether the coupon applies once, forever or for a custom period (referring to the period during which invoices will be generated) * The **eligible products**: select **All products** to apply the coupon to every product, or **Specific products** to select individual products Adding a free trial allows you to start a subscription without charging the customer until a specified period has passed. In Hyperline, a free trial **creates a new phase** that duplicates the first phase, but with all products set to free. To add a free trial, the first phase must include at least one product. The free trial is set to 14 days by default. You can end it after a **custom duration** like 14 days or 1 month, at a **fixed date** or with a **manual end**. You can also end the free trial early with `mark phase as finished`. The free trial details appear on the checkout page if the subscription is configured to start after checkout completion. * **Initial billing date** The initial billing date is when the billing period starts. It defaults to the subscription's start date, as set in the `subscription duration` selector. If the subscription starts on a specific date, you can set the billing date to a custom day (which is always after the subscription start date). * **Align billing period to the first day of the next cycle** Turning the option `on` aligns the next billing period on the first day of the next billing cycle. You can configure this option to be toggled on by default under Settings > Subscriptions. For example, the subscription charges the first billing period from the start date (e.g., January 14, 2025) until the end of the current cycle. For a product billed every month, that's January 31, 2025. From the next cycle onward, billing follows the regular interval (e.g., monthly, from February 1, 2025, to February 28, 2025). This keeps the subscription aligned with the standard billing schedule. * **Phase minimum fee** Set a minimum amount for this phase and optionally select **Eligible products**. An empty selection includes all phase products. See [phase minimum fees](/docs/subscriptions/phases#phase-minimum-fee) for how Hyperline calculates the adjustment. **Shipping address** When shipping details are enabled for the subscription's invoicing entity, you can select one of the customer's saved shipping addresses. Hyperline uses it for this subscription's invoices and tax calculations, including Anrok and Sphere. Leave **Use customer’s default destination** selected to follow the customer's shipping destination. Hyperline uses the billing address when shipping to the billing address, or the default shipping address when shipping to a separate address. See [subscription shipping addresses](/docs/subscriptions/update#shipping-address) for details. **Purchase order** Add a text element that appears in the header of every invoice this subscription issues. **Generate draft invoices**, **Generate documents instead of invoices**, and **Do not charge subscription** are only visible to members with the **Manage subscription invoice settings** permission. Otherwise, the subscription keeps the values inherited from the account, plan, or template. The purchase order, custom invoice note, and minimum fee remain editable with the standard subscription creation permission. **Generate draft invoices** The draft invoices feature allows you to review an invoice before it's sent. It's handy if you have to double-check what's sent to your customer, or when you're first trying out the platform. When Hyperline generates an invoice, it sets it as a draft that you can edit, finalize, and then send to your customer. The customer-level [**Force draft invoices**](/docs/customers/overview#force-draft-invoices) setting overrides this option. When you enable it on the customer, Hyperline creates every invoice as a draft regardless of what you configure here. **Generate documents instead of invoices** When Hyperline generates documents instead of invoices, the documents have no legal value compared to invoices, but you can use them for reporting. You can select whether to add VAT to the document and set a custom name for the document. **Do not charge subscription** Hyperline creates the invoices and marks them as paid, but doesn't charge for them. It's handy for adding subscriptions to your reporting when payment is handled elsewhere. **Minimum fee** Set a global minimum for recurring invoices. It applies to the full invoice after any [phase minimum adjustments](/docs/subscriptions/phases#phase-minimum-fee). ## Subscription payment After clicking **Payment settings**, configure how you want the subscription to start and your customer to pay it. You can also configure invoicing options as an optional step. #### Payment methods This section shows the default payment method and the allowed payment methods. Hyperline uses the default payment method to charge invoices. The customer can add any allowed payment method during checkout and on their portal. You can edit the customer's default payment method and toggle on or off the allowed ones. These changes apply at the customer level. ##### Require payment method for activation Under **Settings > Subscriptions**, the **Require payment method** toggle (off by default) enforces that a customer has a usable payment method before a new subscription can start billing. Turn it on when you want to prevent activating subscriptions that cannot be collected on. When the setting is enabled: * **Manual assignment**: Hyperline blocks new subscription assignments for customers without an acceptable payment method. A callout appears at the top of the assignment form linking directly to the customer's payment method settings so you can add one before assigning. * **Quote signature**: if a customer signs a quote but does not have an acceptable payment method, Hyperline marks the quote as signed but pauses subscription activation. The quote surfaces a **Quote activation paused** callout, and activation resumes automatically once the customer provides an acceptable payment method. In the API, this state is exposed as `error_type: activation_missing_payment_method` on the quote. A customer is considered to have an acceptable payment method when any of the following is true: * Their default payment method type is **bank transfer**, **automated bank transfer**, or **external collection**. These are always considered satisfactory because they do not depend on a stored instrument. * Their default payment method is any other type (card, direct debit, and so on) and its state is **active**. This check only applies to **new subscription assignments**. Updates to existing subscriptions, quote creation and editing, and subscription templates are not affected. #### Checkout session Hyperline provides a hosted checkout page for your customers. It allows them to **enter their billing details** (contact information, address) and **add the payment method** they wish to use for recurring subscription payments. This page is for **single use** and is provided at the beginning of the subscription process to allow your customer to **complete the act of subscribing** to your service. The use of this page is optional. You can disable it by toggling off **Generate checkout session** in the global settings under the Subscriptions section. Additionally, you can add an email address so Hyperline can **automatically send the related checkout page link** to your customer, without any action from your side. #### Activation You now manage subscription activation in the previous step. It aligns with the subscription start strategy (quote signature, checkout completion, manually or at a set date). #### Assign the subscription When everything is set and ready to go, you can click **Assign subscription**. If the customer is going to be charged immediately, Hyperline displays a reminder to prevent you from charging unintentionally. *** ## Using the API If you want a deeper technical integration to start subscriptions with no manual action in the product, you can use the [create subscription endpoint](../../api-reference/endpoints/subscriptions/create-subscription). ``` POST /v2/subscriptions ``` Additionally, you can retrieve the subscription's details using the [get subscription endpoint](../../api-reference/endpoints/subscriptions/get-subscription), or list all of them using the [list subscriptions endpoint](../../api-reference/endpoints/subscriptions/list-subscriptions). ### Create a subscription from a template This example creates a new subscription from the template `subt_7gdusOkqr5L0B8` for the customer `cus_3PYD5R2q5NFK5E`. ```sh theme={null} curl --request POST \ --url https://api.hyperline.co/v2/subscriptions \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "customer_id": "cus_3PYD5R2q5NFK5E", "template_id": "subt_7gdusOkqr5L0B8" }' ``` ### Create a subscription from a list of products This example creates a new subscription with two products paid every month for the customer `cus_3PYD5R2q5NFK5E`. The subscription starts on December 20, 2025 and activates automatically at the start date. Hyperline automatically determines the product prices based on the prices configured in the product catalog for the corresponding currency, interval, etc. ```sh theme={null} curl --request POST \ --url https://api.hyperline.co/v2/subscriptions \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "customer_id": "cus_3PYD5R2q5NFK5E", "starts_at": "2025-12-20T00:00:00Z", "activation_strategy": "start_date", "payment_method_strategy": "current", "products": [ { "id": "itm_4vea8Gj0a5HZr9", "payment_interval": { "period": "months" }, }, { "id": "itm_vBBCZSTR6NzzuL", "payment_interval": { "period": "months" }, "count": 2, }, ] }' ``` Here, product `itm_4vea8Gj0a5HZr9` is a **fee** product and `itm_vBBCZSTR6NzzuL` a **seat** one with 2 items applied. ### Override prices When creating a subscription, you can override the price for a specific product with a custom amount. Note that this operation is only allowed for `flat_fee` products. Here is the previous example, adjusted to override a price: ```sh theme={null} curl --request POST \ --url https://api.hyperline.co/v2/subscriptions \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "customer_id": "cus_3PYD5R2q5NFK5E", "starts_at": "2023-12-20T00:00:00Z", "activation_strategy": "start_date", "payment_method_strategy": "current", "products": [ { "id": "itm_4vea8Gj0a5HZr9", # flat_fee product "payment_interval": { "period": "months" }, "price": { type: "fee", amount: 1234 }, # override }, { "id": "itm_vBBCZSTR6NzzuL", "payment_interval": { "period": "months" }, "count": 2, }, ] }' ``` # Subscription exports Source: https://docs.hyperline.co/docs/subscriptions/exports Export Hyperline subscription data to CSV, including products, prices, ARR, billing cycle, and customer info, for accounting and analysis. If you wish to export your subscription data for external analysis, Hyperline provides you with built-in file export within the Subscriptions section. ## Export flow After you click the export button, Hyperline compiles your subscription data into a CSV file. Download the file to access a complete export, including subscription details, associated customer, estimated ARR, next payment, and more. # Manage a subscription Source: https://docs.hyperline.co/docs/subscriptions/manage Manage the Hyperline subscription lifecycle: activate pending subscriptions, pause invoicing, cancel, reinstate, reactivate, and generate future invoices. ## Activate a pending subscription A subscription stays in `pending` status when you assign it with the **manually**, **after checkout**, or **after quote signature** activation strategy. To activate it: If the subscription's **start date is today or in the past**, the subscription switches to an active state (with a `Live` tag). Hyperline immediately charges products billed at the start of the period. If the **start date is in the future**, the subscription switches to a `Starts on ...` state. This means the subscription is active but hasn't started yet. Hyperline starts charging the products on the start date. ## Pause invoice issuance You can pause a subscription if you want to stop issuing new invoices without cancelling the subscription: Hyperline issues no invoices while the subscription is paused, and the subscription's billing periods stay frozen. They don't renew until you reactivate the subscription. You can reactivate it anytime, instantly or later. When you pause invoice issuance, you can optionally select a date when the subscription automatically resumes. ## Reactivate a paused subscription When you reactivate a paused subscription, you select when it resumes and how Hyperline invoices the paused period. The **Resume invoice issuance** modal opens. * **Today**: the subscription resumes immediately. * **On selected date**: select a date in the past or in the future. * A **past date** resumes the subscription retroactively from that date. The date must be after the pause date. * A **future date** schedules the reactivation. The subscription stays paused until that date, then Hyperline resumes it with the invoicing option you selected. In the **Invoicing** field, select one of the options described in [Invoicing options](#invoicing-options). The modal previews the **Invoices to issue** on reactivation and the **Next invoice** after reactivation, so you can check the amounts before confirming. ### Invoicing options | Option | What Hyperline invoices on reactivation | | - | - | | **Resume at next invoice** (default) | Nothing. The paused period is never billed. | | **Prorate the remaining period** | A prorated invoice for the billing period containing the resume date, from the resume date to the end of that period. Hyperline skips the paused portion. | | **Charge the full period** | Every billing period frozen during the pause, in full, as if the subscription had kept running. | | **Custom charge** | A custom invoice with the line items you select. You can adjust each line's unit price and quantity. | Whichever option you select, regular invoicing resumes on the next scheduled billing date after the resume date. Hyperline only shows **Prorate the remaining period** and **Charge the full period** when they would issue an invoice for the selected resume date. Hyperline applies **Custom charge** immediately, so it isn't available with a future resume date. The examples below all use the same subscription: a monthly plan with a €300 platform fee billed in advance on the 1st of each month. The March invoice is already issued when you pause the subscription on March 10. You reactivate it on May 16. **Resume at next invoice**: The customer stopped using your product during the pause, and you don't want to bill them for it. Hyperline issues no invoice on May 16. April and May are never billed. Hyperline issues the next invoice on June 1 for €300. **Prorate the remaining period**: The customer starts using your product again on May 16, and you want to bill them from that day. Hyperline issues an invoice on May 16 for May 16 to May 31, prorated to 16/31 of €300 (€154.84). April is never billed. Hyperline issues the next invoice on June 1 for €300. **Charge the full period**: You paused invoicing while the customer sorted out an internal budget approval, but they kept using your product. Hyperline issues the April and May invoices (€300 each) on May 16, as if the subscription had never been paused. Hyperline issues the next invoice on June 1 for €300. **Custom charge**: You agreed with the customer to bill a flat €200 to cover the paused period. Select **Custom charge**, keep the platform fee line, and set its amount to €200. Hyperline issues a €200 invoice on May 16. Hyperline issues the next invoice on June 1 for €300. ### Update the reactivation date While a subscription is paused, you can **update the scheduled reactivation date** at any time to postpone or bring forward the automatic restart. You can also **clear the reactivation date** entirely to leave the subscription paused indefinitely. It then only resumes once you manually resume invoice issuance. When a subscription resumes automatically from a date set while pausing, Hyperline uses **Resume at next invoice**. To schedule a reactivation with another invoicing option, click **Resume invoice issuance**, select a future date, then select the option. ## Cancel subscription You can cancel a subscription if a customer wishes to stop it. You can also cancel it if you need to make changes that you can't make through the update subscription option. * **Refund last invoice:** Refunds the total of the last settled invoice to your customer, if available. * **Refund custom amount:** Displays a field for entering a custom refund amount to your customer. * **Refund pro rata:** Refunds a pro-rata amount based on customer usage so far, with a breakdown showing the products and respective balances. * **Do not refund:** Cancels the subscription without issuing a refund to your customer. If you cancel a subscription before Hyperline bills it, you can charge the customer instead. For instance, this happens when the subscription's products are billed at month-end ("end of period") and you cancel mid-month. The options stay the same, except **Refund last invoice**, which adjusts to reflect the estimated amount of the upcoming invoice. Hyperline issues a credit note, visible in the **Invoices** page of this customer. Its category is `Refund` with an item "Refund for invoice X". ## Reinstate a subscription You can reinstate a subscription to keep it running after a cancellation. The flow depends on whether the cancellation already happened. ### Revert a scheduled cancellation If the subscription is still active with a future cancellation date, you can cancel the scheduled cancellation: 1. On the subscription, click **Actions** then **Reinstate**. 2. Click **Reinstate** to confirm. The subscription keeps running as if it had never been scheduled for cancellation. Hyperline issues no invoice. ### Reinstate a cancelled subscription When a subscription is `cancelled`, reinstating it sets it back to `active`. You select when it resumes and how Hyperline invoices the cancelled period. The **Reinstate subscription** modal opens. * **Today**: the subscription resumes immediately. * **On selected date**: select a date after the cancellation date. * A past date resumes the subscription retroactively from that date. * A future date schedules the reinstatement. See [Schedule a reinstatement](#schedule-a-reinstatement). In the **Invoicing** field, select one of the options described in [Reinstatement invoicing options](#reinstatement-invoicing-options). The modal previews the invoices Hyperline issues on reinstatement, so you can check the amounts before confirming. Hyperline restores the subscription's products, phases, and contract terms as they were before the cancellation. #### Schedule a reinstatement When you select a future resume date, the subscription stays `cancelled` until that date. Its status shows **Reinstatement on** followed by the scheduled date. On that date, Hyperline reinstates the subscription automatically with the invoicing option you selected. While a reinstatement is scheduled, you can: * **Change the date or invoicing option**: click **Actions** then **Reinstate**. The modal opens with the scheduled date and invoicing option prefilled. Update them and confirm. To reinstate immediately instead, select **Today**. * **Remove the scheduled reinstatement**: click **Actions** then **Remove scheduled reinstatement**, then click **Remove** to confirm. The subscription stays `cancelled`. **Custom charge** is only available for an immediate reinstatement. You can't select it with a future resume date. #### Reinstatement invoicing options | Option | What Hyperline invoices on reinstatement | | - | - | | **Resume at next invoice** (default) | Nothing. The cancelled period is never billed. | | **Prorate the remaining period** | A prorated invoice for the billing period containing the resume date, from the resume date to the end of that period. The gap between the cancellation and the resume date isn't billed. | | **Charge the full period** | The amount refunded or credited at cancellation, as a re-charge, then every billing period missed up to today, as if the subscription had never been cancelled. | | **Custom charge** | A custom invoice with the line items you select. Hyperline prefills one line per product, covering the cancelled period from the cancellation date to the resume date. You can adjust each line's unit price and quantity. | Hyperline only shows **Prorate the remaining period** and **Charge the full period** when they would issue an invoice for the selected resume date. A monthly plan with a €300 platform fee is billed in advance on the 1st of each month. You cancel it on March 10 with **Refund pro rata**, which refunds the unused part of March. On March 20, the customer changes their mind and you reinstate the subscription from that day. * **Resume at next invoice**: Hyperline issues no invoice on March 20. The customer keeps the March refund. * **Prorate the remaining period**: Hyperline invoices March 20 to March 31, prorated on the €300 fee. * **Charge the full period**: Hyperline re-charges the amount refunded at cancellation, so the customer pays for the full month of March. In every case, Hyperline issues the next invoice on April 1 for €300. ## Generate future invoices You can generate subscription invoices in advance. To do so, go to **Subscription** > **Generate future invoices**, then select the date up to which you want Hyperline to issue invoices. Hyperline advances the subscription to that date, then generates and sends all corresponding invoices immediately. Before confirming, you can **preview the list of invoices** that Hyperline generates, along with their billing periods and amounts. You can also enable the **Group all invoices into one** option to consolidate every generated invoice into a single one, instead of issuing one invoice per billing period. Depending on the payment method: * Hyperline **charges invoices automatically** (credit card, direct debit) * Hyperline marks invoices as **to pay** (bank transfers, outside of Hyperline) ## View past subscription history You can view your past subscription history for better transparency on subscription activities. This feature is particularly useful for tracking changes and cancellations of subscriptions that are no longer active. On a customer's subscriptions page, you can find a section titled **Past subscriptions**. You can also archive a subscription by using the **Delete subscription** action. The subscription then no longer appears in the history list. *** ## Using the API You can also manage subscriptions using the Hyperline API. See the API reference for more details. * [Create subscription update endpoint](../../api-reference/endpoints/subscriptions/create-subscription-update) * [Cancel subscription endpoint](../../api-reference/endpoints/subscriptions/cancel-subscription) * [Reinstate subscription endpoint](../../api-reference/endpoints/subscriptions/reinstate-subscription) # Usage-based product metering Source: https://docs.hyperline.co/docs/subscriptions/metering Configure usage-based products in Hyperline by linking them to aggregators that turn raw events into billable metrics at the end of each period. Usage-based products are a bit more complex than standard products. Hyperline calculates the price of a usage-based product at the end of each billing period, based on the data you send through the events system. You must link each usage-based product to an [aggregator](../usage/aggregators) that defines how Hyperline computes events into a billable metric. To know more about ingesting and managing events, you can read our [dedicated article](../usage/send-usage-data). Metering is especially useful when your pricing depends on an unpredictable and variable usage. If your pricing is committed upfront or doesn't depend on usage data, use the seat-based options instead. ## Pricing configuration To understand how our different pricing models work, you can refer to our [pricing models glossary](../products/overview#pricing-models). As with any other products, you can override metered prices on a per-customer basis directly in the product dropdown. When you override a price, it only applies to your current subscription and appears later on the customer page. ### Min, max and committed amounts You can add safety thresholds to your subscription to ensure your customer won't pay below or above a certain price. Minimum and maximum amounts apply to prices. Hyperline shows the correct usage and the capped or floored price on both the invoice and the interface. Committed units are another way to set up a minimum committed amount. If the actual usage is under the threshold value, Hyperline shows the minimum committed usage instead. ## Metering periods You can configure metering options when assigning a subscription manually or in a plan if you need to reuse the product. Metering is only available for dynamic products and the configuration will appear below the price preview within the product dropdown. Hyperline offers several metering periodicities that should cover most use cases. Don't hesitate to reach out to us if you feel like you need something different. #### Option 1: Same as payment interval This option will select all billable events for which the `timestamp` value is within the current subscription period of the product. This is the most common and straightforward option for most use cases, like billing overheads for a given subscription period or standard usage-based pricing. For example, take a product billed every month with a metering period set to `Same as payment interval`. If the current subscription period is Sept 1st - Oct 1st, Hyperline takes into account all events with a timestamp between these dates. #### Option 2: Current contract period This option will select all billable events for which the `timestamp` value is within the current subscription committed period. This is useful when billing usage-based past a certain annual threshold (for instance your customer is allowed 10M€ of spend every year with additional usage billed monthly). For example, on a subscription committed yearly from Jan 2023 to Jan 2024, Hyperline takes into account all events within that timeframe. #### Option 3: Current phase This option will select all billable events for which the `timestamp` value is within the subscription's current [phase](../subscriptions/phases). A phase is a bounded section of a subscription with its own start and end date. The metering window automatically follows the phase you're on and resets when the next one starts. Use it when a product's pricing is scoped to a specific phase of a deal. For example, a ramp-up phase that meters usage for its full duration independently of the payment interval or the overall contract period. The subscription overview shows the metered period as the phase's date range. #### Option 4: Whole database This option will configure Hyperline to not take into account the timestamps of your events and include all of them in each invoice. It's useful to automate a seat-based billing based on realtime data for instance. ### Only bill the difference with the last invoice This option tells Hyperline to only bill the difference between usage for your current period and your previous period. It's only available for the last 3 options. It's particularly helpful when you're billing overages. For instance, coming back to the 10M€ example, if you want to bill the additional revenue every month you don't want to re-bill previously billed revenue. When you select this option, Hyperline takes into account the total usage billed the last month and subtracts it from the current period usage. ## Include child customers' usage When a customer has child customers through [organisation-based billing](../customers/organisation-based), a usage-based product can bill the parent subscription on usage from the parent and its direct children. Use this when the parent owns the contract, but several child customers send usage events. Each child keeps its own customer record and usage history, while the subscription on the parent calculates one metered charge. To enable it, open the usage-based product configuration while creating or updating the subscription, then turn on **Include child customers' usage**. You can then select how Hyperline combines usage: * **Sum across child customers** adds the parent usage and each direct child's usage together. * **Max across child customers** bills only the highest-consuming customer among the parent and its direct children. Child usage roll-up applies to direct child customers only. It is configured per usage-based product on the subscription, so you can roll up usage for one metered product while keeping another product billed only on the parent's own usage. # Subscriptions overview Source: https://docs.hyperline.co/docs/subscriptions/overview Understand the Hyperline subscription model: a contract between you and a customer, with products, pricing, terms, and scheduled future changes. In Hyperline, the subscription model represents a contract between you and a customer. A contract is a sold configuration of products and their prices, with a set of terms and optionally pre-configured future changes. You can create subscriptions from the customer page in the UI, from the CRM, or through the API. ## Subscriptions lifecycle A customer can have one or multiple subscriptions running at the same time. These subscriptions can be active, scheduled to start in the future, or started and scheduled to be cancelled. Hyperline's flexible subscription model lets you configure multiple products with different options and renewal logic. You can also add multiple phases (scheduled changes), all combined inside a unique contract. Hyperline lets you set a commitment period, which may differ from the billing interval of the products it encompasses. Furthermore, the billing intervals can also vary between different products. Depict intricate scenarios, such as a customer who subscribes annually (annual commitment) but pays for a product based on monthly usage. The same subscription can also include an add-on with a fixed price paid quarterly. When you create a subscription, its default status is `pending` and it can be activated: * automatically at the scheduled start date * when a customer signs its associated [quote](../quotes/overview) * when a new customer completes its associated [checkout](../subscriptions/checkout-page) * manually in the interface * using the API Once a subscription is active, Hyperline shows it with a `live` green tag. Once a subscription is active, Hyperline **automatically invoices it** following the schedule described below. If you need to pause invoicing, you can pause the subscription directly in the interface using the pause subscription option. For more details, see [Manage a subscription](../subscriptions/manage). ## Subscription status Here is a description of each subscription status: * `pending` The subscription has been created and won't be charged until it is activated using one of the options described above. * `active` The subscription is running and Hyperline invoices it at the next payment date. * `cancelled` The subscription has been cancelled from an active state. You can [reinstate it](/docs/subscriptions/manage#reinstate-a-cancelled-subscription). * `voided` The subscription has been voided directly from the pending state without ever being activated. * `paused` The subscription's invoicing is paused and its billing periods are frozen until it is reactivated. * `errored` Hyperline attempted 4 times (3 retries) and failed to charge a subscription's invoice. See [Handling payment errors](../payments/payment-errors). Hyperline then considers the subscription inactive because the customer failed to pay you. Hyperline won't invoice the customer in the future or collect payment. You can choose to reactivate it manually. ## When is a subscription billed? Hyperline lets you decide if each product is billed at the start or at the end of the billing period independently. Usage-based products will always be billed at the end of the period, depending on the final consumption. Create a yearly subscription with a flat fee billed at the start of the period, and add-ons billed at the end of each quarter. #### Products charged only once You can assign products billed only once. This is useful for charging implementation or onboarding fees. You can also bill these products at the start or end of the period. Once billed, Hyperline detaches them from future invoicing. #### Subscriptions with start and end of period products You can assign one product charged at the beginning of the period and another charged at the end, with the same billing period (e.g., monthly). Hyperline groups these products within the same invoice. Your subscription has a product "Platform Access" billed at the start of period, and a product "API Calls" billed at the end of period. Both products are billed monthly, and grouped within the same invoice. Example for an invoice generated on September 1st: * Platform Access's billing period will be September 1st > September 30th (in advance) * API Calls' billing period will be August 1st > August 31st (in arrears) * The global billing period of the invoice will span over two months (August 1st > September 30th). # Subscription phases Source: https://docs.hyperline.co/docs/subscriptions/phases Split Hyperline subscriptions into phases with different products and coupons to build ramp-up deals, free trials, and evolving contracts. Phases split a subscription into sections for granular deal customization. Like subscriptions, phases have a start and end date and contain products and coupons. Use phases to invoice upfront fees, build ramp-up deals, and model evolving contracts within the same subscription. Transition from one phase to the next automatically or manually. In the example above, you charge your customer a **setup fee** of 1000.00 € automatically once they sign their quote. You then manually start their **recurring fee** of 20 licenses at 20.00 €/license/month. After one year, the recurring fee automatically increases to 40 licenses at 25.00 €/license/month. ### Add phase To add phases to your subscription you can: * **Create empty phase** to add a new phase and start from scratch. * **Duplicate phase** to duplicate the content (products, coupons). For every phase other than the first one, the start strategy is `previous phase end`. If the previous phase end strategy is set to `forever`, Hyperline changes it to `manual end` when you add a new phase. Hyperline then sets the last phase end strategy to `forever`. When you set the subscription to end on a fixed date, the new phase starts the next day. You can also add phases to live subscriptions through [update subscription](./manage#generate-future-invoices). ### Phase transition Phases transition automatically once the phase end strategy is reached (date, duration, or manual). There are two types of transitions: * **Direct**: Hyperline charges the new phase according to its configuration, without taking the previous phase balance into account. New billing intervals for every product start on the day the phase transitions. Your current phase contains 10 licenses costing 100€ monthly, with the current cycle running from September 1st to September 30th. You transition to a new phase on September 15th containing 20 licenses costing 200€ monthly. On September 15th, Hyperline issues a new invoice of 200€. The new billing interval is September 15th to October 15th. * **Pro-rata**: Hyperline generates an adjustment invoice that contains the balance owed or due from the previous phase and what is owed for the next phase. The amounts are based on the invoicing schedule of the products. The new phase may contain the same products with the same billing interval (for example, monthly or yearly). In that case, Hyperline preserves the billing interval and aligns all products with the same billing interval to it. Your current phase contains 10 licenses costing 100€ monthly, with the current cycle running from September 1st to September 30th. You transition to a new phase on September 15th containing 20 licenses costing 200€ monthly. On September 15th, Hyperline issues a new invoice of 50€ (new phase due amount = 200\*(15/30) = 100€) − (previous phase surplus = 100\*(15/30) = 50€). The billing interval remains September 1st to September 30th, then October 1st to October 31st, and so on. ### Update products and coupons You can add, remove and update products and coupons during the current phase following the same pattern as subscriptions without phases. For future phases, changes to products and coupons apply immediately. ### Phase minimum fee In a phase's **Advanced settings**, enter a **Phase minimum fee**, then optionally select **Eligible products**. Leave the selection empty to include all products in the phase. You can set a different minimum for each phase, including in subscription templates. When eligible products are billed, Hyperline compares their total after discounts and before tax with the phase minimum. If the total is lower, it adds a **Minimum fee adjustment** for the difference. Invoices containing only mid-cycle updates do not trigger a phase minimum. For example, a €300 phase minimum with €220 in eligible charges adds an €80 adjustment. Charges for unselected products remain unchanged. If you also configure a global **Minimum fee** under **Invoicing**, it applies afterward to the full invoice total, including phase adjustments. Clear the phase minimum amount to disable it and clear its product selection. ### Update phase start and end strategy For current phases, you can update the phase end strategy for any date or duration later than the current time. For future phases, you cannot set the phase end date before the end date of the previous phase. ### Transition to next phase When there is a next phase, you can manually transition the current phase with immediate effect. # Subscription templates Source: https://docs.hyperline.co/docs/subscriptions/templates Pre-configure reusable subscription templates in Hyperline that auto-fill products, pricing, billing cycles, and contract terms during assignment. When assigning new subscriptions to your customers, Hyperline lets you create pre-configured and reusable templates. Subscription templates support all configuration options and parameters available when creating subscriptions. When you select a template during the subscription assignment flow, Hyperline automatically fills the form with all configurations from the selected template. You can still customize all details inherited from the template in the final customer subscription without affecting the original template, typically configured by an admin. Subscription templates are the evolution of plans. They are more powerful, flexible, and future-proof. **Plans are deprecated and will be removed in summer 2026.** Use subscription templates instead of plans to benefit from the latest features and improvements. Hyperline does not provide automatic migration from plans to templates, since templates offer significantly more flexibility and capabilities. However, the Hyperline team can assist in assigning template IDs to existing subscriptions to ensure continuity in tracking. ## Configuration Templates have a name (which becomes the subscription name when assigned, though you can override it during creation) and an optional internal description. They can include multiple subscription configurations, each with a currency and, optionally, a country for which it is eligible. If no specific country is defined, the configuration applies to all countries. Each subscription configuration supports all the same options as a standard subscription form, including contract settings, invoicing preferences, products/coupons, multi-phase setups, ... By adding multiple configurations to the same template, you can pre-configure variations by currency or market while keeping them under a single template. Hyperline also provides a one-click action to duplicate configurations, saving time when creating similar setups for another currency. You cannot create duplicate configurations within a single template for the same currency/country pair. If needed, create separate templates. ### Price inheritance When you configure a template, Hyperline suggests product prices from the catalog and copies them into that template. If you later update product catalog prices, template prices will **not** automatically change. This prevents unintended modifications and ensures stability for legacy offers. You can still update template prices manually if desired. ## Subscription assignment When you assign a new subscription to a customer, Hyperline only suggests templates matching the customer’s currency and country. If multiple configurations match, Hyperline automatically selects the most specific one. For example, a template has three configurations: 1. EUR: eligible for all countries 2. EUR: eligible for France 3. GBP: eligible for the UK If you select this template for a French customer using EUR, Hyperline applies configuration **2 (EUR/France)**, even though configuration 1 also matches. ## Quote templates You can also use subscription templates in quote templates. This enables quotes with fully pre-filled subscription configurations, reducing manual work, minimizing errors, and promoting internal standardization. ## Updating templates When you update a subscription template (currency, country, or configuration), Hyperline does **not** automatically update existing subscriptions linked to it. This allows you to evolve offers without affecting active subscriptions. You can still update existing subscriptions manually using the [subscription update flows](./update), independently of the template. # Subscription translation overrides Source: https://docs.hyperline.co/docs/subscriptions/translations Store custom product names and descriptions per Hyperline subscription so invoices stay translated for multilingual customers despite catalog edits. Translation overrides let you save custom product names and descriptions directly on a subscription. Once enabled, future catalog edits won't affect that customer's invoices. Without overrides, Hyperline uses catalog translations when available, or falls back to the main product field. ## Set a default for all subscriptions Go to **Settings → Subscriptions** and enable **Override product translations on subscriptions**. New products added to any subscription will have the override on by default. Existing subscriptions are unaffected. ## Enable per product When creating or editing a subscription, scroll to the bottom of any product and toggle on **Override product translations**. A globe icon appears on the name and description fields. The toggle only appears when the customer has a language set that differs from the invoicing entity's language. When both are the same, the main field already covers the only relevant locale. ## Edit translations Click the globe icon to open the translation panel. It shows one tab per language, limited to the customer's and invoicing entity's languages. The **Current** tab (customer's language) stays in sync with the main field automatically. ## Templates Templates show all available languages in the translation panel since no customer is attached. When assigned to a customer, the stored values carry over and the customer's language is marked **Current**. ## Precedence From lowest to highest: **default** (`false`) → **subscription settings** → **template** → **subscription product**. A higher-level value always wins. ## FAQ Hyperline reverts to catalog translations (or the main field if none exist). Your custom values are preserved on the subscription and restored if you re-enable the override. Either the customer has no language set, or the customer and invoicing entity share the same language, in which case no separate translation tab is needed. Yes. The same globe icon appears on name and description fields when editing an invoice manually. # Update subscription Source: https://docs.hyperline.co/docs/subscriptions/update Update active Hyperline subscriptions globally or locally: change products, prices, quantities, and contract terms with previews and version history. You can edit subscriptions from the subscription details page. There are two types of updates: * **Global update** where you can update the whole subscription directly * **Local update** where you can update a single part of the subscription (product price, contract configuration...) Updating a subscription is not available for subscriptions that are in a future state after [generating future invoices](./manage#generate-future-invoices) or that have a [quote for subscription update](../quotes/subscription-update) pending signature. You can still create additional update quotes in that state. All open update quotes are listed on the **quotes** tab of the subscription details page. For cancelled, voided, or archived subscriptions, you can only update simple fields (contract value, estimated ARR, CRM opportunity ID, and shipping details display). ## Global update You can update a subscription by clicking **Update subscription** in the subscription action dropdown. Hyperline then shows the following options: ### Simple update When you select this option, Hyperline updates the subscription immediately, keeps the billing intervals, and does not generate a pro-rated invoice. This is recommended when updating product information or adding, removing or updating a product or coupon without impacting the current billing period. ### Advanced update When you select this option, you enter a multi-step process to configure exactly when and how Hyperline applies the update, as well as manage the transition invoice precisely: Select when the subscription update should take effect: * **Next renewal**: Hyperline applies the update when the current billing cycle ends * **At last renewal**: Hyperline applies the update retroactively as of the start of the current billing cycle * **Immediately**: Hyperline applies the update right away * **Scheduled date**: Hyperline applies the update at a specific date in the future Decide how you want to configure the updated subscription: * **Update current subscription**: Modify the existing subscription configuration directly * **Update to a template or a plan**: Reset the subscription configuration using a pre-defined template or plan as a starting point, that can be further customized if needed Define how Hyperline handles the billing cycle and invoicing during the transition: **Billing cycle alignment** * **Keep current period**: The subscription continues with its existing billing dates * **Start new period**: The subscription billing dates are reset to start a fresh cycle from the update date **Transition invoice** * **Waive transition invoice**: Hyperline doesn't issue a transition invoice * **Issue transition invoice**: Hyperline issues a single transition invoice to settle the current billing period before the update takes effect. This invoice nets the credit for the outgoing configuration and the charge for the new one. * **Issue separate credit note and invoice**: Hyperline refunds the current billing period's invoice via a credit note and issues a separate invoice to reflect the updated subscription configuration. Available for updates **At last renewal**, and for Spanish invoicing entities on every schedule (see the note below) The **Issue transition invoice** option is not available when the subscription has products billing in a future period (for example, after using [generate future invoices](./manage#generate-future-invoices)). You can still proceed with the update by waiving the transition invoice. **Spanish invoicing entities**: when the invoicing entity is registered in Spain (`ES`), Spanish invoicing rules do not allow a single netted transition invoice. **Issue transition invoice** is hidden and **Issue separate credit note and invoice** is the only way to issue a transition invoice. This applies regardless of the effective date (**At last renewal**, **Immediately**, or **Scheduled date**). Hyperline cancels the current period's invoice with a credit note and issues a new invoice for the updated configuration. At this step, you can preview both the **transition invoice** and the **following invoice** to understand the financial impact before confirming. The transition invoice settles the period before the update. The following invoice is the first invoice after the update. **Refunding transition credit notes**: When the update creates a credit note, Hyperline follows the invoicing entity's **Refund credit notes to wallet by default** setting. If the setting is disabled, payments made by card or direct debit are refunded to the original payment method, while credit notes for bank transfers remain open. [Learn how to configure the default refund destination](../invoices/refunds#set-the-default-refund-destination). ### Scheduled updates A subscription with a scheduled update cannot be updated until the scheduled update is applied or cancelled. However, you can manage the scheduled update through the subscription dropdown: * **Revise update**: Edit the scheduled update configuration * **Cancel**: Cancel the scheduled update entirely, allowing the subscription to be updated again ### Subscription versions You can access previous subscription versions, as well as scheduled updates, through the versions tab. *** ## Local update If you do not wish to update the entire subscription at once, but rather just a single part, you can proceed with a local update. ### Duration You can edit the subscription or phase end date to end at a later or closer date with the following options: * Forever * After a custom relative duration * At a specific date You cannot set the end of the phase or subscription before the end of the current billing period of its products. In order to do that, you need to [cancel the subscription](./manage#cancel-subscription). If the subscription has not started yet, you can edit the start date too. ### Products You can edit the price and quantity of products that currently belong to a subscription, and add or remove them freely. #### Update product price You can edit prices immediately by clicking the product `...` then **Update price**. The price updates immediately and applies to the next invoice. #### Update product quantity You can edit the quantity (except for usage-based and connected seats) by clicking the product `...` then **Update quantity**. The quantity change **always applies immediately**. Two settings control only how it is billed: * **Payment schedule** sets *when billing happens* (not when the change applies): * **Immediately**: a separate invoice (or credit note) is issued and charged right away. * **Next invoice**: the adjustment is added as a line on the next invoice. * **Update method** sets how the adjustment is computed: * **Pro-rata**: only the remaining or elapsed portion of the period. * **Full price**: the full period amount. * **Do not charge / refund**: apply the new quantity without any billing. An adjustment can be a **charge** (positive line) or a **credit** (negative line), and in some cases no line appears at all. The outcome depends on whether the product is billed at the **start** of the period (in advance) or at the **end** of the period (in arrears). It also depends on the direction of the change (increase or decrease). See [Subscriptions with start and end of period products](/docs/subscriptions/overview#subscriptions-with-start-and-end-of-period-products). | Billing timing | Update method | Quantity increase | Quantity decrease | | - | - | - | - | | Start of period (in advance) | Pro-rata | Charge (prorated) | Credit (prorated) | | Start of period (in advance) | Full price | Charge (full) | No line (already paid) | | End of period (in arrears) | Pro-rata | Credit (prorated) | Charge (prorated) | | End of period (in arrears) | Full price | No line (billed at end) | Charge (full) | With **Full price**, Hyperline doesn't produce an adjustment line for an end-of-period increase or a start-of-period decrease. For an increase, the regular end-of-period invoice bills the added quantity at full price. For a decrease, the customer already paid for the removed quantity in the current period. **Do not charge / refund** never bills the customer, but whether a line is recorded depends on the payment schedule: * **Immediately**: nothing is billed and no invoice is generated. * **Next invoice**: a **zero-amount line** is added to the next invoice to record the change (labelled as not invoiced for the period). For worked billing examples of each case, see [Connected seats billing calculation examples](/docs/subscriptions/connected-seats#billing-calculation-examples), which uses the same start and end of period, pro-rata, full, and no-charge logic. This dialog always applies the change immediately. To apply a quantity change on a **future date**, use an [Advanced update](#advanced-update) instead. #### Add product You can add products directly to a live subscription by clicking **Add product**. You can add products with an existing price configuration or configure them manually. Hyperline adds them to the subscription immediately. You can charge them at full price, pro-rata, or not at all, either immediately or on the next invoice. #### Remove product You can remove products from the subscription immediately by clicking the product `...` then **Remove product**. Depending on the product balance, you can charge or refund them at a pro-rata or full price, or without payment, either immediately or with the next invoice. ### Coupons You can add or remove coupons freely from the subscription, with immediate effect. #### Add coupon You can add coupons directly to a live subscription by clicking **Add coupon**. You can then configure the coupon name, application, discount type and products to which it is applied. When adding a coupon with a duration (e.g., 6 months) during a subscription update or transition, the coupon's expiration date is automatically calculated from the transition date. This ensures the coupon applies for the correct duration starting from when the update takes effect. #### Remove coupon You can remove coupons from the subscription immediately by clicking the coupon `...` then **Remove coupon**. ### Contract You can attach, edit, or remove a contract from the subscription at any time. ### Invoicing You can edit the invoicing configuration at any time, with an impact on invoices emitted after the update. Changing **Generate draft invoices**, **Generate documents instead of invoices**, or **Do not charge subscription** requires the **Manage subscription invoice settings** permission. Without it, these advanced options are hidden and keep their current values. The purchase order, custom invoice note, minimum fee, and invoicing schedule remain editable with the standard subscription update permission. #### Shipping address Shipping controls are available only when shipping details are enabled for the subscription's [invoicing entity](/docs/account/invoicing-entities). In the subscription's **Invoicing** settings, select a saved customer address in **Shipping address**, then save your changes. Only shipping addresses are listed. The selected address applies to invoices created after the update and their tax calculations, including Anrok and Sphere. Existing invoices keep their original address. To remove the subscription-specific address, select **Use customer’s default destination**: * If the customer's shipping destination is the billing address, Hyperline uses the billing address without a separate shipping address. * If the customer's shipping destination is a separate shipping address, Hyperline uses the customer's default shipping address. A saved address cannot be deleted while a subscription references it. First change the address on each subscription that uses it, or select **Use customer’s default destination**. ##### Tax ID for a shipping location If the selected shipping address has its own tax ID, your subscription quotes and new invoices use that ID. Otherwise, they use the customer's tax ID. This also applies when the subscription follows the customer's default shipping destination. Shipping to the billing address uses the customer's tax ID. You can configure an address tax ID through the customer address API. Clearing it restores the customer default. Every subscription using that address shares the override; changing it does not update existing invoices. If you set an explicit tax ID on an invoice, that invoice's value takes precedence. For Anrok and Sphere, the tax calculation uses the selected destination and the resolved tax ID. Different tax IDs remain on separate invoices during daily subscription-invoice consolidation. Use location tax IDs for registrations belonging to the same customer. If separate subsidiaries buy independently, create separate customers and group them in an [organisation](/docs/customers/organisation-based). # Upfront metered products Source: https://docs.hyperline.co/docs/subscriptions/upfront-metering Bill usage-based products upfront at the start of each period based on projected consumption, then true-up against actual usage on the next invoice. By default, a usage-based product is invoiced **in arrears**, at the end of the billing period, once all usage for that period has been consumed. Hyperline also supports the opposite pattern: **upfront metered products**, where usage is invoiced at the *start* of each period and reconciled against real consumption on the next invoice. This is useful when: * Your customer has a **minimum committed volume** and you want to charge for it upfront each period. * You want cash to come in at the start of the period rather than the end. * Your customer's usage is fairly predictable period-over-period. Upfront billing is a property of a **usage-based (dynamic) product** on a subscription. You configure it by setting the product's payment schedule to **start of period** when adding it to the subscription or plan. ## How it's billed At the start of each period, real usage for that period hasn't happened yet, so Hyperline has to bill on a projection. The projection is: ``` billed units = max(committed units, usage billed for the previous period) ``` * **Committed units** is the minimum volume you configure on the product (`min_committed_count` on the API). It acts as a **floor**, not a cap. * **Previous period's billed usage** is what actually got consumed in the period that just closed. Two consequences follow from this rule: * **On the very first period** there is no prior usage, so the customer is billed on the committed amount. If you didn't set a commitment, the upfront charge for the first period is **zero** and the whole charge lands on the correction line the following period. * **On subsequent periods** the upfront charge floats up if the last period ran hot. If a customer consumed 500 units when they committed to 250, the next period's upfront charge is priced on 500. The commitment is only a floor. ## The correction line item Because you charged the customer upfront on a projection, real usage will drift from what was billed. To reconcile, **every renewal invoice includes a correction line item for the period that just closed**: ``` correction = actual usage for that period (priced) − amount already invoiced upfront ``` * If the customer **used more** than what was billed upfront, the correction is a **debit** (extra charge). * If the customer **used less**, the correction is a **credit** (refund). A typical renewal invoice for an upfront metered product therefore contains **two lines** for that product: 1. **Upfront charge** for the new period, sized on `max(committed, last period's usage)`. 2. **Correction** for the previous period, settling the difference between actual and projected usage. Corrections are pre-populated on the next period's draft invoice as soon as the current invoice is finalized, and are kept in sync as new usage events arrive. This way, both you and your customer can see the running true-up before the invoice is issued. ## Worked example Setup: * Metered product priced at **€50 per unit**, billed monthly, upfront. * Committed units: **250 per month**. **January (first period)** * No prior usage yet → billed on the committed 250 units. * Upfront charge: `250 × €50 = €12,500`. * Actual January usage turns out to be **500 units**. **February renewal invoice** * Upfront charge for February: `max(250, 500) × €50 = 500 × €50 = €25,000`. * Correction for January: `500 × €50 − 250 × €50 = €12,500` **debit** (customer used more than was billed upfront). * Total on the February invoice for this product: `€25,000 + €12,500 = €37,500`. **March renewal invoice**: assume February usage came in at **300 units** * Upfront charge for March: `max(250, 300) × €50 = 300 × €50 = €15,000`. * Correction for February: `300 × €50 − 500 × €50 = −€10,000`, applied as a **€10,000 credit** (customer used less than was billed upfront in February). * Net on the March invoice for this product: `€15,000 − €10,000 = €5,000`. **April renewal invoice**: assume March usage came in at **200 units** (below commitment) * Upfront charge for April: `max(250, 200) × €50 = 250 × €50 = €12,500`. The commitment kicks in as the floor. * Correction for March: `200 × €50 − 300 × €50 = −€5,000` credit. * Net on the April invoice for this product: `€12,500 − €5,000 = €7,500`. ## Interaction with other settings ### Metering period The projection and the correction always look at usage **within the product's own billing period** (the period being billed upfront and the one being trued up). If you configure a different metering period (`Current contract period`, `Current phase`, `Whole database`, `Custom`), the same upfront + correction mechanic applies. However, the "actual usage" figure used in the correction reflects that broader window rather than a single billing period. ### Only bill the usage difference The **Only bill the difference with the last invoice** option combines with upfront billing. Hyperline charges the customer upfront for the projected units, and the correction on the next invoice reflects only the incremental usage vs. what was previously billed, rather than the full period's usage. Use this when the priced quantity is a running total (e.g. cumulative revenue against an annual threshold) rather than a per-period consumption count. ### Min and max amounts Minimum and maximum **amounts** on the product are applied to each invoiced amount independently. Both the upfront line and the correction line are subject to the caps in force at the time they are computed. ## When not to use upfront metering Upfront metering is a poor fit if: * Usage is highly volatile and you don't want large corrections swinging invoice totals up and down. * The customer has no meaningful commitment. You'll end up billing zero upfront and everything on the correction, which is just arrears with extra steps. * You need revenue tied precisely to consumption events with no timing gap. In that case, use standard (in-arrears) metering. # Aggregators Source: https://docs.hyperline.co/docs/usage/aggregators Configure aggregators to transform raw usage events into billable metrics for subscription products or assign them to customers for usage monitoring. Aggregators turn raw usage events into a single metric, such as API calls, active users, or storage consumed. You can use that metric for subscription billing or, with the Customer Intelligence module, assign it directly to customers for monitoring without billing them. You manage aggregators independently in **Usage > Aggregators** and can link them to multiple products. ## Subscription billing or direct customer assignment An aggregator can reach a customer in two ways: | Configuration | How the aggregator applies | Billing impact | Availability | | - | - | - | - | | Through a subscription | Link the aggregator to a usage, credit, or connected seat product, then add that product to a subscription | The aggregated value drives the product's billing or credit consumption | Included with the relevant billing feature | | Directly assigned to customers | In the aggregator's **Visibility** settings, select all customers or specific customers and segments | Monitoring only; no product, subscription, or invoice line is created | Requires the Customer Intelligence module | You can use the same aggregator in both configurations. If it is both part of a subscription and assigned directly to the same customer, Hyperline avoids showing a duplicate usage card. The subscription's metering period takes precedence for the subscription-linked card. Direct assignment is not an alternative way to bill usage. It only exposes the metric on the selected customer records for monitoring, analysis, and threshold alerts. ## Operations An aggregator uses one of three operations to compute a usage metric from your events: ### Count Counts the number of matching events. Use this when you bill based on the number of occurrences (e.g., API calls, logins, transactions). ### Sum Sums the value of a specific numeric property across matching events. Use this when you bill based on a cumulative measure (e.g., data transferred in GB, compute hours consumed). When using **Sum**, you must specify which event property to aggregate. ### SQL formulas Use **SQL formula** when Count or Sum is not enough, and you need to combine, compare, or adjust values before billing them. A formula runs on the events selected by the aggregator's **Event type** and **Filters**. SQL formulas use a restricted calculation syntax: they do not accept arbitrary SQL operators, functions, or queries. #### Supported syntax | Category | Supported syntax | | - | - | | Arithmetic | `+`, `-`, `*`, `/`, and parentheses | | Aggregate functions | `sum()`, `avg()`, `min()`, `max()`, `first()`, `last()`, and `count()` | | Calculation functions | `greatest()`, `least()`, `coalesce()`, and `nullif()` | | Conditional function | `if(property = value, resultIfTrue, resultIfFalse)` inside an aggregate function | | Comparisons in `if()` | `=`, `!=`, and `<>` | Every formula must contain at least one aggregate function. Write numeric event properties directly by name and place every property reference inside an aggregate function: | What you need | Formula pattern | | - | - | | Sum a numeric event property | `sum(totalAmount)` | | Count matching events | `count(*)` | | Count events where a property is present | `count(totalAmount)` | | Average a numeric event property | `avg(unitPrice)` | | Keep the highest matching value | `max(seats)` | | Keep the lowest matching value | `min(seats)` | | Keep the earliest matching value | `first(seats)` | | Keep the most recent matching value | `last(seats)` | `first(property)` and `last(property)` use the value from the earliest, respectively the most recent, matching event that contains the property. Events are ordered by their event timestamp; if timestamps match, `first()` uses the event received first and `last()` the one received last. Both only look at events **inside the billing period**. No value is carried over from an earlier one. If you only send an event when the value changes, a period in which nothing was sent counts as 0. In that case, `first()` returns the first value sent *within that period* rather than the value in force when it started. To bill on `first()`, make sure your integration sends at least one event per billing period. You can then combine those results: | Billing rule | Formula | | - | - | | Bill at least 500, even if usage is lower | `greatest(sum(totalAmount), 500)` | | Remove an included allowance | `greatest(sum(totalMinutes) - 50000, 0)` | | Cap the billed value | `least(max(seats), 1000)` | | Apply a per-event adjustment | `sum(totalAmount) - sum(if(type = 'one_off', 500, 0))` | #### Unsupported syntax Hyperline rejects anything outside the supported syntax above. This includes: * SQL queries and clauses such as `SELECT`, `FROM`, `WHERE`, and `CASE` * Other SQL operators, including `ANY`, `AND`, `OR`, `>`, `>=`, `<`, and `<=` * Arbitrary SQL functions, casts, aliases, comments, and semicolons * Nested aggregate functions such as `sum(max(seats))` Use **Test formula** before saving to preview the result on matching events. Use property names exactly as they appear in your events. Wrap names containing spaces or special characters in double quotes, for example `sum("total amount")`. Text values in conditions use single quotes, for example `type = 'one_off'`. ## Configuration When creating an aggregator, you configure the following: * **Name**: A descriptive label for the aggregator * **Event type**: The type of event to aggregate (e.g., `api_calls`, `storage`, `users`) * **Operation**: Count, Sum, or SQL formula (and the target property for Sum) * **Unit name**: The label displayed alongside aggregated values (e.g. `API calls`, `GB`, `seats`). Surfaces on usage charts, prices, invoices, and the customer portal. * **Filters**: Optional conditions to narrow which events are included. Filters support AND/OR logic with operators like `equals`, `in`, `gte`, `lt`, etc. * **Exposed event keys**: Event fields to surface in the UI for transparency and debugging * **Allow negative values**: Whether the aggregated result can go below zero The unit name is configured on the aggregator itself. It used to live on each product; products linked to an aggregator now inherit its unit name automatically. ### Default aggregation interval You can set a **default aggregation interval** on an aggregator by specifying a count and a period (days, weeks, months, or years). It is used to display and evaluate the metric when the aggregator is assigned directly to customers without a subscription. For an aggregator used through a subscription, the subscription's metering period determines the current value instead. The aggregator's default interval does not change how that subscription is billed. ## Aggregator filters Aggregator filters let you define **named filter sets** on an aggregator. Each filter combines conditions using AND/OR logic on event properties (e.g., `region equals "eu"`, `plan in ["pro", "enterprise"]`). Filters serve two purposes: * **Billing**: different prices can apply based on which filter an event matches (see [price metering filters](#price-metering-filters)) * **Usage visualization**: on the [customer Usage tab](./customer-usage), each filter appears as a separate line on the usage chart with its own color and legend entry You can only delete a filter if no product price references it. ## Thresholds Thresholds let you define **alert conditions** on an aggregator. Each threshold specifies: * **Name** (optional): A descriptive label for the threshold * **Operator**: Greater than or equal to (`>=`) or less than or equal to (`<=`) * **Value**: The numeric threshold value Thresholds are evaluated separately for each customer to whom the aggregator applies: * For a subscription-linked aggregator, Hyperline uses the subscription's metering period. * For an aggregator assigned directly to customers, Hyperline uses its default aggregation interval. This direct monitoring workflow requires the Customer Intelligence module. When a customer's aggregated usage crosses a threshold, Hyperline can notify you via [webhooks](../../developers/webhooks) (`aggregator.threshold_crossed` event) or [Slack notifications](../../integrations/slack). A threshold alert does not create a charge or change an invoice. On the [customer Usage tab](./customer-usage), thresholds appear as dashed horizontal reference lines on the usage chart, with the operator and value shown as labels. ## Which products use aggregators? Not all product types require an aggregator. Here's when you need one: | Product type | Aggregator required? | Allowed operations | | - | - | - | | **Fee** | No | — | | **Seat** | No | — | | **Connected seat** | Yes | Count only | | **Usage** | Yes | Count, Sum, SQL formula | | **Credit** | Yes | Count, Sum, SQL formula | A seat product becomes a [connected seat](/docs/subscriptions/connected-seats) product when an aggregator is selected. ## Managing aggregators Navigate to **Usage > Aggregators** to create, edit, and delete aggregators. ### Create an aggregator Click **New aggregator**, configure the operation, event type, and optional filters, then save. ### Edit an aggregator Click an existing aggregator to update its configuration. The detail page also shows which products are currently linked to this aggregator. ### Delete an aggregator You can only delete an aggregator if no products are linked to it. ## Linking an aggregator to a product When creating or editing a usage-based, credit, or connected seat product, you select an existing aggregator from a dropdown instead of configuring metering inline. * **Usage products**: select any aggregator (count or sum) * **Credit products**: select any aggregator (count or sum) * **Seat products**: select a count aggregator (only when connected seats are enabled) For more details on product configuration, see [Products and prices](/docs/products/overview). ## Price metering filters For usage-based products, you can further refine billing by adding **metering filters at the price level**. This allows different prices for the same product based on specific event properties (e.g., region, instance type). Learn more in the [usage-based product documentation](/docs/products/overview#metering-configuration). # Connect with BigQuery Source: https://docs.hyperline.co/docs/usage/bigquery Connect a Google BigQuery dataset to Hyperline as a data loader to pull usage events automatically, with service account permissions and queries. This guide is specific to setting up a data loader with [Google BigQuery](https://cloud.google.com/bigquery). To learn more about data loaders in general, you can read our [general article](./usage-data-with-connectors). ## Authorizations To set up our BigQuery connector, you'll need to configure a Service Account with the right permissions. To do so, you can follow these steps: 1. Go to the Google Cloud Console for the project containing your database and navigate to the [IAM & Admin](https://console.cloud.google.com/iam-admin) tab. 2. Click **Create Service Account**, enter a name and description for the service account, then click **Create**. 3. Assign the following roles to the service account: **BigQuery Data Viewer** and **BigQuery Job User**, then click **Continue** and **Done**. 4. Find the newly created service account in the list and click it. Go to the **Keys** tab, click **Add Key**, and select **Create new key**. Select **JSON**, then click **Create**. ## Load your data To get started, just go to the [data loaders page](https://app.hyperline.co/app/events/loaders) in Hyperline, create a new connection and select "Google BigQuery" in the dropdown list. Copy and paste the content of the JSON key file in the correct box, enter a name and then save the connection. When creating or updating a connection, Hyperline always performs a ping test to check that the database is accessible. If the test passes, your connection is ready. # Customer usage Source: https://docs.hyperline.co/docs/usage/customer-usage Monitor per-customer consumption from subscription-linked and directly assigned usage aggregators with real-time charts, thresholds, and event details. The **Usage** tab on a customer page gives you a real-time overview of aggregator-based consumption for that customer. It can show aggregators from running subscriptions and aggregators assigned directly to the customer through the Customer Intelligence module. | Source | Why the aggregator appears | Period used | | - | - | - | | Running subscription | A product in the subscription is linked to the aggregator | The subscription's metering period | | Direct assignment | The aggregator is assigned to all customers or to matching customers and segments | The aggregator's default aggregation interval | Assigning an aggregator directly to a customer without a product or subscription is a Customer Intelligence feature. It provides usage monitoring and threshold alerts, but does not bill the customer. ## Aggregator cards Each aggregator appears as a card showing: * **Aggregator name** and linked subscription (if any) * **Current aggregated value** for the active metering period * **Area chart** of the aggregated value evolution over time (last 6 months by default) * **Threshold lines** displayed as dashed horizontal references on the chart, with the operator and value as labels (see [thresholds](./aggregators#thresholds)) ### Filters on charts When an aggregator has [aggregator filters](./aggregators#aggregator-filters) defined, the chart displays **one line per filter** with a distinct color. A legend below the chart identifies each filter by name. ### Card display logic The Usage tab handles different scenarios to avoid duplicated cards: | Scenario | Display | | - | - | | Aggregator from a subscription | Current value + subscription's metering period | | Directly assigned aggregator + 1 subscription | Current value + that subscription's metering period | | Directly assigned aggregator + multiple subscriptions | One card per subscription, each with its own metering period | | Directly assigned aggregator + no subscription | Current value + the aggregator's default aggregation interval | ## Period range and grouping Use the date range picker at the top of the Usage tab to select a custom period. You can also select how data is grouped: | Group by | Best for | | - | - | | **Monthly** | Long-term trends (presets: last 3/6/12 months, current/past year) | | **Daily** | Weekly or monthly analysis (presets: this/last week, current/past month) | | **Hourly** | Intraday monitoring (presets: today, yesterday, this/last week) | Each aggregator card updates to show the aggregated value for the selected period, and charts are filtered accordingly. Numbers in cards and tooltips use a compact format (e.g. `1.2K` instead of `1,200`). ## Sorting You can sort aggregator cards by: * **Name** (ascending or descending) * **Current value** (ascending or descending) ## Explore consumption Click **Explore** on any aggregator card to open a side panel with the underlying events. The selected date range and grouping are forwarded to the panel. The exploration panel provides: * **Event list** filtered on the aggregator's event key, with timestamps and values * **Search** to find specific events * **Date range filter** to narrow the time window * **Filter selector** to view events matching a specific aggregator filter * **Pagination** for browsing through large event sets From the card's dropdown menu, you can also navigate directly to the aggregator detail page or the linked subscription. ## Related * [Global usage](./global-usage): same charts aggregated across all customers, with a per-customer ranking drill-down * [Aggregators](./aggregators): define how raw events become a usage metric * [Custom usage tracking](../customer-intelligence/custom-usage-tracking): assign aggregators to customers without a subscription # Explore usage events and consumption Source: https://docs.hyperline.co/docs/usage/explore-usage-consumption Explore raw usage events in Hyperline at global, customer, subscription, and invoice levels, or pull events programmatically through the API. In the Hyperline platform, an event is a specific action or occurrence that can be tracked and measured. You can explore it in the **Events** section or retrieve events programmatically via the [API](../../api-reference/endpoints/billable-events/get-events). This view is global and shows all tracked events. However, for each subscription and invoice, you can explore a more detailed view of the events. ## Explore usage data You can view the product's consumption along with the amount billed for each event. To do so, use the **Explore consumption** action, available at different levels: ### Open data consumption on subscription ### Explore invoice consumption ### Explore consumption on customer portal In the customer portal, you can delve into the consumption details of each subscription. You can find them in the **Subscription Details** section. Here, you can view and analyze the usage data associated with each subscription. ## Download usage data You can export usage data in CSV format for analysis and processing. ### Export single product events To download events for a specific product, click the **Export CSV** button in the consumption view. The CSV file includes the following columns: ### Export all invoice events When viewing an invoice with multiple usage-based products, you can download all events at once as a ZIP file containing separate CSV files for each product. Click the **Export all events** button on the invoice page. The ZIP file is named `events-{invoiceNumber}.zip` and contains one CSV file per product, with filenames based on the product names. This is particularly useful when you need to analyze usage data across multiple products for a single billing period. ## Customize displayed event name You can customize the event name when you create or edit the product. Hyperline uses it to identify the event in the consumption. To give each event a dynamic name, you can base it on a specific key of the event. ## Customize exposed columns In the product editing section, you have the option to customize the columns that appear in the consumption CSV export. # Getting started with usage-based billing Source: https://docs.hyperline.co/docs/usage/getting-started Build your first usage-based billing workflow in Hyperline: send events, create an aggregator, configure a metered product, and bill a subscription. Usage-based billing lets you charge customers based on what they consume: API calls, transactions, storage, compute hours, seats, AI usage, or another measurable activity. Monetizing AI products? See [Monetize an AI product](/guides/monetize-ai-products) for guidance on usage-based billing, prepaid credits, wallets, and hybrid pricing patterns for AI products. In Hyperline, the setup has four building blocks: | Building block | What it does | | - | - | | **Usage events** | Raw customer activity sent to Hyperline through a CSV import, API, data loader, or test simulation. | | **Aggregator** | Turns usage events into one billable metric, such as a count of API calls or the sum of stored gigabytes. | | **Usage product** | Defines what you sell and how that metric is priced. | | **Subscription** | Assigns the product to a customer, with billing, payment, and metering settings. | Start with one simple usage metric before adding tiered pricing, filters, commitments, or spending caps. It is easier to validate the full billing flow when the first setup is intentionally small. ## Before you start Make sure you have: * A customer to test with, or permission to create one in **Customers** * A usage metric you want to bill, such as API calls, processed transactions, or storage volume * Usage data available through one of the supported ingestion methods * A [test mode](/docs/getting-started/sandbox) workspace if you want to experiment before billing real customers You sell an API product with a monthly platform fee and a usage-based add-on. The add-on bills each customer for the number of API calls they make during the month. To set this up, you send API call events to Hyperline and create an aggregator that counts those events. Then you link the aggregator to a usage product and add that product to the customer's subscription. ## Setup flow ### 1. Connect usage data Hyperline needs usage events before it can calculate a usage-based charge. Select the ingestion method that matches where your usage data already lives: Upload usage events from a spreadsheet or exported report. Send events from your application or backend systems. Pull usage data from a connected database or warehouse. Create test usage directly from a customer page in test mode. For each event, Hyperline needs enough information to identify the customer, event type, timestamp, and usage properties you want to bill or filter on. If you are still exploring the model, use [simulated events](./simulate-usage-data) in test mode. You can validate the subscription and invoice behavior before connecting a production data source. ### 2. Create an aggregator Go to **Usage** > **Aggregators**, then click **New aggregator**. An aggregator defines how Hyperline turns raw events into a billable number. Configure: * **Event type**: the event category to measure, such as `api_call`, `transaction`, or `storage_snapshot` * **Operation**: how the metric is calculated * **Unit name**: the label shown in usage charts, prices, invoices, and the customer portal * **Filters**: optional rules that include only matching events | Operation | Use it when | | - | - | | **Count** | Each matching event should count as one unit, such as one API call or one transaction. | | **Sum** | A numeric field on the event should be added up, such as gigabytes stored or compute minutes. | | **SQL formula** | You need a custom calculation, such as applying an allowance, cap, or adjustment before billing. | Learn more in [Aggregators](./aggregators). ### 3. Create a usage product Go to **Products**, click **New product**, then select **Usage**. When configuring the product: 1. Add the product name and description. 2. Select the aggregator you created. 3. Configure at least one recurring price. 4. Select the pricing model and tiers that match your commercial offer. 5. Save the product. For a simple first setup, use one recurring price with a straightforward rate. You can add advanced pricing later, such as volume tiers, basis points, or price-level metering filters. You configure usage products in the product catalog, then reuse them in quotes, subscriptions, and customer-specific agreements. See [Products and prices](/docs/products/overview#usage) for the full product setup reference. ### 4. Add the product to a subscription Once the usage product has a recurring price, assign it to a customer subscription. 1. Open the customer page. 2. Click **Actions** > **Assign new subscription**, or go to **Subscriptions** and click **New subscription**. 3. Select the customer and subscription start date. 4. Click **Add product** and select the usage product. 5. Review the product price, billing interval, and metering settings. 6. Open **Payment settings**. 7. For testing, select **Manually later** so you can create the subscription without collecting payment immediately. 8. Click **Assign subscription**. After the subscription is assigned, Hyperline starts tracking usage for the product based on the subscription's metering period. If the customer has both fixed and usage-based charges, add both products to the same subscription. This keeps the recurring fee and usage charges together in the customer's invoice flow. ### 5. Check usage and invoices After events are connected and the subscription is active, validate the setup from the customer page: * Open the customer's **Usage** tab to see current aggregator consumption. * Open the customer's **Subscriptions** tab to review usage on the active subscription. * Click **Explore** or the usage detail icon to inspect the events behind the total. * Open the customer's **Invoices** tab to check the `open` invoice preview for the current period. An `open` invoice is a live preview. For usage-based subscriptions, it updates as new events are recorded. At the end of the billing period, the invoice enters the configured grace period before it is finalized and sent for payment. ## Common first checks If the subscription does not show the usage you expect, check these items first: * The event timestamps fall inside the subscription's current metering period. * The event type matches the aggregator's **Event type**. * The event belongs to the same customer as the subscription. * The aggregator filters do not exclude the events. * The usage product is included in an active subscription. For more invoice behavior details, see [Invoice terms](/docs/invoices/term). ## Next steps Walk through an end-to-end usage-based subscription setup. Learn how count, sum, formulas, filters, and thresholds work. Monitor consumption and inspect the events behind each metric. Understand subscription-level metering periods and usage windows. Is something still unclear? Don't hesitate to reach out to our team via the in-app chat if you need additional support. # Global usage Source: https://docs.hyperline.co/docs/usage/global-usage View aggregator usage across all Hyperline customers from one place, drill into top consumers, and analyze billable metric trends in real time. The **Usage** section gives you a client-wide view of every [aggregator](./aggregators), with a chart per aggregator covering all customers and all subscriptions. From there, you can drill into any aggregator to see which customers are driving its consumption. Access it from the sidebar under **Usages > Usage**. ## Aggregator cards Each aggregator appears as a card showing: * **Aggregator name** and unit (e.g. `API calls`, `GB`) * **Total aggregated value** for the selected period across all customers * **Area chart** of the value evolution over time, with one line per [aggregator filter](./aggregators#aggregator-filters) when filters are defined * **Threshold lines** as dashed horizontal references when [thresholds](./aggregators#thresholds) are set on the aggregator Numbers are rendered with a compact format (e.g. `1.2M` instead of `1,200,000`) so cards stay readable at a glance. ## Period and grouping Use the date range picker at the top of the page to select a custom period. You can also select how data is grouped: | Group by | Best for | | - | - | | **Monthly** | Long-term trends (presets: last 3/6/12 months, current/past year) | | **Daily** | Weekly or monthly analysis (presets: this/last week, current/past month) | | **Hourly** | Intraday monitoring (presets: today, yesterday, this/last week) | Presets adapt to the selected grouping. Hyperline keeps filter values in the URL, so you can share a view by copying the link. ## Sorting and search Sort cards alphabetically by name, ascending or descending. Use the search box to narrow the list when you have many aggregators. ## Group by customer Click **Explore consumption** on any usage card to open a side panel. It ranks customers by their contribution to the aggregator over the selected period. The panel shows: * **Customer**: name and link to the customer's profile * **Value**: that customer's aggregated total for the period (compact format) Rows are ordered by total descending (top consumers first) and paginated 20 at a time. The date range and grouping are inherited from the parent page. You can refine the breakdown to a single [aggregator filter](./aggregators#aggregator-filters) using the filter selector. The explore panel allows you to compare contributions across multiple filters, switch the selected filter or open the panel from a different aggregator card. ## Aggregator details From the card's dropdown menu, you can open the aggregator's detail page to review its configuration (operation, event type, filters, thresholds) or edit it. See [Aggregators](./aggregators) for the full configuration reference. ## Permissions The `usages_read` permission controls access to the **Usage** section. Manage permissions per role from **Settings > Roles**, under the **Usage** group. Existing roles that already had the `events_read` permission were granted `usages_read` automatically. New roles must opt in. ## Related * [Aggregators](./aggregators): define how raw events become a billable metric * [Customer usage](./customer-usage): same charts scoped to a single customer * [Explore your data usage](./explore-usage-consumption): drill into raw events from a subscription or invoice # Import events with a CSV file Source: https://docs.hyperline.co/docs/usage/import-events-csv Import usage events into Hyperline in bulk by uploading a CSV file from Google Sheets, Excel, or any spreadsheet editor with required fields. You can import events in bulk by uploading a CSV file. You can create your CSV using tools like **Google Sheets**, **Excel**, or any spreadsheet editor.\ Writing the CSV manually is possible but **not recommended** due to the risk of formatting mistakes. ## Required fields Each event row must include: * **`timestamp`**: When the event occurred, in **ISO 8601** format. * **`event_type`**: The name of the event. This value is flexible and later used when configuring your products. * **`customer_id`** * **`record/id`**: A unique identifier for the event.\ Uploading another event with the same `record/id` will overwrite the previous one. ## Custom fields You can add as many custom fields as needed. All custom fields must start with the prefix **`record/`**.\ For example, to create a field named `count`, name the column **`record/count`**. ## Upload your file To begin, open the **[Events Explorer](https://app.hyperline.co/app/events/explore)** in Hyperline. Click **Import events from CSV** in the top-right corner to open the upload modal. You can also download a **CSV template** from the same modal.\ The template includes the correct header row and a sample event to help you get started. After selecting your file, click **Import CSV file** to start the upload.\ If the file contains no errors, Hyperline imports your events and makes them ready for analysis. ## Manually writing the CSV file When preparing your CSV file, make sure it follows these rules: * Use **commas** as field separators. * Wrap fields in **double quotes** if they contain commas or line breaks. * Always include a **header row** to describe each column. * Use the **ISO 8601** format for the `timestamp` field. * Use a consistent format for nested fields, such as `record/id` or `record/amount`. * All standard fields are required. `record/` fields are optional, and you can declare as many as needed. ### Example Below is an example of a valid CSV file.\ (`record/type` and `record/is_live` are only examples. You can define your own fields.) ```csv theme={null} timestamp,event_type,record/id,record/type,record/is_live,customer_id "2023-11-07T13:59:40.536Z",api_call,1245,"paid",true,"cus_foXtwuyW7NsCH-" "2023-11-07T13:59:40.536Z",api_call,1152,"to_pay",true,"cus_foXtwuyW7NsCH-" "2023-11-07T13:59:40.536Z",api_call,8625,"pending",false,"cus_foXtwuyW7NsCH-" "2023-10-18T15:53:24.772Z",api_call,9752,"closed",true,"cus_foXtwuyW7NsCH-" "2023-10-18T15:53:24.772Z",api_call,7052,"open",true,"cus_foXtwuyW7NsCH-" ``` Notes: * `record/id` is numeric and does not require quotes. * String fields (such as `record/type`) must be enclosed in quotes. * Boolean fields (such as `record/is_live`) do not require quotes. # Connect with MongoDB Source: https://docs.hyperline.co/docs/usage/mongodb Connect a MongoDB database to Hyperline as a data loader to pull usage events automatically, without writing custom integrations or API code. This guide is specific to setting up a data loader with [MongoDB](https://www.mongodb.com). To learn more about data loaders in general, you can read our [general article](./usage-data-with-connectors). ## Connect to your database To get started, just go to the [data loaders page](https://app.hyperline.co/app/events/loaders) in Hyperline, create a new connection and select "MongoDB" in the dropdown list. To set up our MongoDB connector, you'll just need a valid database URL. You can also pass additional parameters within the URL if you need custom options. ## Load your data Create a new data loader directly below the new connection. Hyperline asks you to provide a JSON query. Your query needs to include a `collection` attribute pointing to your base collection. Unlike traditional SQL providers, MongoDB doesn't allow direct aggregation queries without a default collection. A simple query to load 3 fields from a collection would typically look like this. Everything outside of "collection" must be a valid MongoDB query field (you can use aggregate, lookups, filters...). Hyperline parses the JSON from your input and transforms it into a valid MongoDB query to run on the connected server. Make sure to include an `id`, `customerId` and `timestamp` field with the correct casing. # Connect with PostHog Source: https://docs.hyperline.co/docs/usage/posthog Connect a PostHog Cloud project to Hyperline and import product events into usage-based billing using a scheduled HogQL query data loader. You can connect a PostHog Cloud project to Hyperline and use its product events as usage data. Hyperline runs a [HogQL query](https://posthog.com/docs/sql) on a schedule and imports the results as events. Hyperline supports PostHog Cloud projects hosted in the EU or US. The connection uses read-only query access. ## Connect your PostHog project 1. Go to **Settings** > **Integrations** in Hyperline. 2. Find **PostHog** and click **Connect**. 3. Sign in to PostHog if prompted. 4. Select one PostHog project and authorize Hyperline. After authorization, Hyperline automatically creates a PostHog connection on the [data loaders page](https://app.hyperline.co/app/events/loaders). You do not need to copy an API key or project ID. ## Create a data loader 1. Go to the [data loaders page](https://app.hyperline.co/app/events/loaders). 2. Click **New data loader**. 3. Select the PostHog connection created for your project. 4. Enter the event type that Hyperline should use for the imported records. 5. Select how often Hyperline should refresh the data. 6. Enter a HogQL query and preview the results. Your query must return these fields with the exact casing: * `id`: a stable, unique identifier for the record * `customerId`: the Hyperline customer ID or external ID associated with the record * `timestamp`: when the event occurred For example, the following query imports PostHog events named `api_call`: ```sql theme={null} SELECT uuid AS id, distinct_id AS "customerId", timestamp, properties.endpoint AS endpoint FROM events WHERE event = 'api_call' ``` In this example, each PostHog `distinct_id` must match a Hyperline customer ID or external ID. You can select additional event properties when you need them for aggregation or pricing. Filter the query to include only billable events and properties. This keeps each refresh focused on the data Hyperline needs for billing. 7. Check that the preview contains the expected customers and records. 8. Save the data loader. Hyperline imports the query results on the selected schedule. For more information about customer matching, record updates, and required fields, see [Pull usage data with connectors](./usage-data-with-connectors). ## Next steps * [Configure aggregators](./aggregators) * [Explore usage consumption](./explore-usage-consumption) * [View customer usage](./customer-usage) # Send usage data Source: https://docs.hyperline.co/docs/usage/send-usage-data Send usage events to Hyperline through the API to drive usage-based billing, with guidance on event design, payload structure, and best practices. Sending usage data is the first thing to do to unlock Hyperline's potential when you have a usage-based model. Here are a few tips to make the most out of Hyperline. First, **Hyperline is not an analytics API**. Sending page views, user logins or other non-critical events doesn't really make sense as you probably won't use them for your pricing and packaging anyway. This being said, you shouldn't refrain from sending data that you're not using yet. Hyperline is designed for you to iterate on your pricing & packaging. It lets you run experiments and simulations from the data Hyperline has ingested. The best way to think about events to send to Hyperline is to ask yourself if you'll use the data either * To price your product (ex: price per user or per API call) * To limit usage (ex: free up to 5GB of storage) * To orchestrate pricing-related workflows (ex: when a customer reaches X, show a paywall). When in doubt, just send it. Once it's in the system, you'll be able to play with it and may discover some new opportunities. ## Ingestion basics Event payloads always follow the same structure, and you can send them to the [POST `/events` endpoint](../../api-reference/endpoints/billable-events/ingest-billable-event). The `record` object can contain any additional properties of type `string`, `number`, `boolean`, and arrays of these types. Hyperline rejects arrays of objects. Hyperline processes events instantly. You can go to your [events page](https://app.hyperline.co/app/events/explore) and refresh it to see them. The events ingestion API is rate-limited to 1,000 requests per 10 seconds. When sending events in batch, each request can contain up to 5,000 events. See [rate limiting](/developers/rate-limiting) for more details. Here's an example payload: ```json Event theme={null} { "customer_id": "cus_fh4585Jjrekkk", "timestamp": "2022-01-05 21:56:52", "event_type": "new_transaction", "record": { "id": 485, "amount": 2500 } } ``` ## Security and privacy Even though Hyperline makes some basic security checks, it can't automatically filter every piece of personal or confidential data from its systems. Most of the time you don't need personal information in Hyperline so remove or obfuscate (for instance, John becomes J\*\*\*): * People names * People's personal email addresses * Phone numbers * Payment information like card numbers or IBANs * Physical addresses * Anything that could help identify someone or their location Hyperline is responsible for keeping your data safe in its systems, but you're in charge of the content itself. Be careful: your customer's safety is an important matter. ## Events or entities? Hyperline is designed to rely fully on events for data ingestion. Hyperline can then apply a variety of operators to configure how you want to aggregate data (count, sum), and filters (equals, "is null" check, greater/lower than comparators, etc.). In the first case, Hyperline will treat your events as *entities* or *models*, meaning that one event will represent one item in Hyperline's database, independently of its timestamp. For instance, if you want your customer to pay 5€ per user, send the following *event* to Hyperline when a new user registers. ```json Event theme={null} { "customer_id": "", // Hyperline ID or external ID of the existing customer "timestamp": "2023-11-12T00:00:00.000Z", // used to aggregate depending on the billing period "event_type": "users", // use the name you want "record": { "id": 258, "work_email": "l***.c***@yourcompany.com", "created_at": "2023-11-12T00:00:00.000Z", "deleted_at": null // we'll use this field later } } ``` Then you'll create a dynamic product that counts your users, and apply a volume pricing to it by defining an interval and the related pricing tiers. Hyperline offers a preview of this pricing so you can see how it evolves as the number of items increases. ## Update and delete events Now you may be thinking, what happens if you send an event that shouldn't be billed? Or if you need to make a change to an entity? Hyperline's API is an append-only system, meaning that it doesn't allow update or delete operations outside the Hyperline interface. You can still correct events using the methods below. ### Updating an event Each event is identified by a unique key composed of 2 parameters: * `event_type` * `record.id` When Hyperline detects a new event with the exact same 2 keys, it considers that this new event overrides the previous one and replaces it in the database. In other words, updating an event is just like creating one: resend the event with the same `event_type` and `record.id`, and Hyperline replaces the matching event. To find out which event is the latest, Hyperline uses the `timestamp` value. When you resend an event, Hyperline updates only the `record` (payload) and `timestamp` fields. The `customer_id` and `event_type` fields are **immutable**. They remain as set by the original event and are ignored on update. If you need to change the customer associated with an event, delete the original event and create a new one. Using the users example again, here's an example where you add a "status" property: ```json theme={null} { "customer_id": "", "timestamp": "ACTIVE_DATE", "event_type": "users", "record": { "id": 258, "status": "premium", "work_email": "l***.c***@yourcompany.com", "created_at": "2022-01-01 10:00:00", "deleted_at": null } } ``` The event in the database will now have a `premium` status and the previous version will not exist anymore. If you need to keep both versions, you'll need to provide a different `record.id`. ### Deleting an event If you sent an event by mistake, you can delete it in the **Events** tab on the app. But this is not the way to manage *standard* deletions, for instance when a user is removed from an account. There are many ways to manage this. The first one is to use the `deleted_at` key you added earlier and set it to something different than `null`. Then update the usage product you created earlier to filter out records where `deleted_at` is not null like so. Another option is to use a state or a flag in the model, for instance, an `active` boolean field in the user entity that you can toggle to off. The principle stays the same, just set a property to the right value and filter out the elements you don't want. ## Retrieve events via API You can retrieve billable events programmatically using the [GET `/v1/events` endpoint](../../api-reference/endpoints/billable-events/get-events). This allows you to: * Query events by event type * Filter by customer, record IDs, or timestamp range * Sort results in ascending or descending order * Paginate through large result sets This is useful for building custom analytics, auditing usage data, or integrating event data into your own systems. ```bash Example request theme={null} curl -H "Authorization: Bearer " \ "https://ingest.hyperline.co/v1/events?event_type=api_call&customer_id=cus_xyz789×tamp_gte=2024-01-01T00:00:00Z" ``` ## Limitations In order to process massive numbers of events, Hyperline had to adopt a *rigid* structure for events. While quite permissive, there are 2 main limitations: * Record properties can't be nested (only one level of properties is allowed) * Records can't have more than 25 properties # Simulate usage data Source: https://docs.hyperline.co/docs/usage/simulate-usage-data Simulate usage events in Hyperline's sandbox without code to test usage-based subscriptions and explore billing behavior before going to production. Want to test Hyperline by creating your first usage-based subscription for a customer, but don’t have technical skills or simply want to move fast? This guide is for you. In the [sandbox (Test mode) environment](https://sandbox.app.hyperline.co), you can simulate usage data with fake events for any customer in just a few steps. 1. Go to one of your customers → ***Events*** tab 2. Click ***Simulate new events*** 3. Fill in the ***Event type*** field with the event name used to aggregate usage in your product configuration, along with the date and number of events to create. Optionally, you can add extra parameters using the JSON ***Payload*** field 4. Click ***Create new events*** Events may take a few seconds to be ingested. You’ll see them appear in your customer’s ***Events*** page, and you can easily delete them afterward if needed. You can also view the customer’s subscription usage details and updated next payment amount in the ***Subscription*** tab. You can also check the ***open*** invoice (the next invoice to be charged at the end of the billing period) in the ***Invoices*** tab. Note: it may take a few minutes for the invoice to appear. # Connect with Snowflake Source: https://docs.hyperline.co/docs/usage/snowflake Connect a Snowflake warehouse to Hyperline as a data loader to pull usage events automatically, with credentials and query configuration steps. This guide is specific to setting up a data loader with [Snowflake](https://www.snowflake.com). To learn more about data loaders in general, you can read our [general article](./usage-data-with-connectors). ## Connect to your database To get started, just go to the [data loaders page](https://app.hyperline.co/app/events/loaders) in Hyperline, create a new connection and select "Snowflake" in the dropdown list. Fill in the form with your connection details (account ID, username, warehouse, database, schema, role). Hyperline only needs read access to the tables you need to synchronize. ### Authentication Hyperline supports two authentication modes for Snowflake, selectable from the **Authentication** dropdown in the connection form: * **Password**: authenticate with the Snowflake user's password. * **Key pair (RSA)**: authenticate with an RSA private key that is registered on the Snowflake user. Snowflake is [deprecating single-factor password authentication on August 31, 2026](https://www.snowflake.com/en/blog/blocking-single-factor-password-authentification/). If your connection uses a password today, plan to migrate to key-pair authentication (or another supported method) before that date to avoid disruption. #### Password authentication Select **Password** and enter the user's password in the **Password** field. #### Key pair (RSA) authentication Select **Key pair (RSA)** and provide: * **Private key**: the RSA private key registered on the Snowflake user, in PEM format. Paste the full key including the `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----` lines (or the encrypted equivalent). * **Private key passphrase** *(optional)*: the passphrase protecting the private key, if it is encrypted. Leave empty for unencrypted keys. Refer to Snowflake's [key-pair authentication guide](https://docs.snowflake.com/en/user-guide/key-pair-auth) for instructions on generating a key pair and assigning the public key to a Snowflake user. ## Load your data Snowflake is a standard SQL loader and you just need to write a Snowflake compatible SQL query. Hyperline runs it as the role or user you used to connect to the database. As always, make sure to include `id`, `customerId` and `timestamp` fields with the correct casing. # Pull usage data with connectors Source: https://docs.hyperline.co/docs/usage/usage-data-with-connectors Pull usage data from your own database into Hyperline using connectors for PostgreSQL, BigQuery, Snowflake, and MongoDB without writing API code. If you prefer not to integrate the Hyperline API, you can use connectors to import data directly from your own database. ## Prerequisites * You need a Postgres database that can receive incoming traffic from our IPs `15.188.105.163`, `15.188.215.105` and `35.181.129.14` * The associated database URL (should look something like `postgres://username:password@host.com/database`) As a best practice, use a read replica and create a dedicated user for Hyperline. Limit this user's access to the subset of data Hyperline needs. ## Load your data To get started, go to the [data loaders page](https://app.hyperline.co/app/events/loaders) in Hyperline. You should see an empty state. Add your first connection by clicking **New connection**. In the modal: * Select a provider * Give a name you'll remember to your connection * Enter the URL you got from the prerequisites When you click **Submit**, Hyperline runs a blank query to check that your database is accessible. Your connection then appears as live. Next, create your first loader by clicking **New data loader** on the right side of the screen. In the modal: * Select the connection you just created * Set an event type for this query. Hyperline uses this identifier to refer to the data from this query. For example, `api_calls` or `active_users` * Select the refresh rate for your use case. Every hour is usually enough to get started ## Getting the SQL right Now write your query. Hyperline expects the query output to follow a specific format. Hyperline requires 3 fields to validate the query: * `timestamp`: The date used to determine whether a record falls within a billing period. For example, if you bill monthly API calls, only events with a timestamp within the current billing cycle are included. This field is less critical if your pricing does not rely on periodic metering. * `customerId`: The Hyperline ID or external ID of the customer. This field is used to associate each record with the corresponding customer. * `id`: A unique identifier for the record (can be an ID from your system). Hyperline uses this field to de-duplicate and update records, so ensure it uniquely represents each record. When importing records, Hyperline tries to match an existing customer. If no match exists, Hyperline creates a new customer with the status `automatically_created`. To avoid clutter, these customers don't appear in your customers list by default. You can access them in the `pending customers` table. Optionally, you can also return a `customerName` property. Hyperline uses it to name the customer on creation, which makes the customer easier to find later. To summarise, the minimum acceptable request looks like this: ```sql theme={null} -- Make sure to use quotes in postgres to make the query case sensitive SELECT id, company_id as "customerId", created_at as timestamp from api_calls ``` Or to import the customer name: ```sql theme={null} -- Adding customer name SELECT id, company_id as "customerId", companies.name as "customerName", created_at as timestamp FROM api_calls LEFT JOIN companies on companies.id=api_calls.company_id ``` This is the minimum for Hyperline to accept and load a query. You can add other fields to your query. Only include what's necessary to keep data sharing to a minimum. Then click **Preview query**. Hyperline checks that the required fields are present and displays a preview of 5 records so you can verify the output. Save the data loader and go to your events page. After a few seconds, a table with your newly ingested events appears. Use this page as a debugger to check your data. ### Updating records Hyperline automatically updates existing records. It uses the combination of the supplied `id` and `customerId` and always keeps the latest version. Hyperline doesn't update customer names, even if the name has changed. To change a name, update it in the interface. ### Deleting records Hyperline doesn't delete records automatically. Instead, add a `deletedAt` field to the query and set it when the record is deleted. You can then filter these records out in the Hyperline pricing engine. ### Loading big tables Hyperline processes queries in batches of up to 120k rows per minute. If your table is bigger than this, import only records updated after the last refresh, or import them less often. ```sql theme={null} -- Adapt this to your refresh time SELECT xxx FROM table WHERE (updated_at + interval '60 minutes') > NOW() ``` # Manage wallet balance Source: https://docs.hyperline.co/docs/wallets/balance Top up Hyperline customer wallets via prepayment, offline payments, free funds, the customer portal, or the API, and track every wallet movement. ## Top up a wallet You can add funds to a customer's wallet in several ways: 1. Initiate a prepayment from the customer's default automatic payment method 2. Record an offline payment received outside Hyperline 3. Add free funds 4. Let customers top up independently from the customer portal 5. Top up through the API **Paid top-ups** are funds your customer pays for, acting as a prepayment. **Free top-ups** are an offer you are making to the customer. ### Initiate a prepayment Use **Initiate prepayment** when the customer has a default automatic payment method, such as card or direct debit. Hyperline charges that payment method and adds the settled funds to the wallet. The payment transaction and wallet movement provide the audit trail. Hyperline does not create an invoice, receipt, or payment advance document for the top-up. ### Record an offline payment Use **Add offline payment** when the customer has already paid outside Hyperline and you want to make those funds available in their wallet. Hyperline does not create a technical invoice, receipt, or payment advance document. You can select one of two sources: * **Use existing transaction**: select a compatible transaction that still has an unallocated amount. Hyperline adds its complete remaining amount to the wallet. * **Record transaction**: record a new payment received by bank transfer or another external payment method, then add it to the wallet. For a new transaction, enter the payment date, payment method, amount, and an optional reference. You can also add an optional comment to the wallet movement. The reference belongs to the payment transaction; the comment belongs to the wallet transaction. Offline payments only support **Bank transfer** and **External payment method**. A stored card or direct debit method requires a real provider charge and cannot be used to record an offline payment. The transaction must belong to the same customer and use the wallet currency. If part of it is already allocated to invoices, Hyperline adds only the remaining unallocated amount to the wallet. You can also fund the wallet while recording an offline payment from the customer's **Transactions** page. Turn on **Add payment funds to wallet** in the **Record transaction** > **Payment** form to make the recorded amount available in the wallet immediately. See [Understand payment allocations](/docs/payments/allocations#record-a-transaction-received-outside-hyperline). A customer sends a €300 bank transfer. You allocate €100 directly to an invoice, then add the remaining €200 to their wallet for future invoices. ### Free top-ups Use **Add free funds** when you want to credit a wallet without collecting payment. Hyperline adds the funds to the wallet and creates a credit note for accounting purposes. You can create the credit note immediately or keep it as a draft first. You must enable free wallet loads in wallet settings before you can add free funds. ### API top-ups You can also top up wallets through the API. Use the API when you want your own product, backend workflows, or internal tooling to trigger wallet loads. ### From the customer portal You can let your customers top up independently through their portal. For this, you have to go to the [wallet settings](/docs/wallets/overview) first. **Top-up limitations** It is currently not possible to add more than \$100 in one payment to a wallet. The total balance of a wallet also can't be more than \$500 for payments made through a customer portal. Paid top-ups added through Hyperline have no limitations. They must add a credit card as a payment method to do so. Clicking **Top-up** on this screen will trigger an immediate payment from the registered credit card and credit the wallet instantly. The payment transaction and wallet movement remain available for tracking. No invoice or receipt is created for the top-up. ## Wallet debit Hyperline automatically debits customer wallets when the feature is enabled in the wallet settings and the wallet has a positive balance. Hyperline uses wallet funds to pay subscriptions, related invoices, and one-time payments. A wallet cannot have a negative balance. Hyperline automatically deducts the maximum possible amount from the wallet when paying invoices. Hyperline charges any remaining amount to the customer's default payment method. You can also pay a specific invoice from the customer's wallet manually. Open the invoice, select **Actions** > **Add payment**, then select **Use wallet balance**. Enter the amount to apply, up to the lower of the invoice amount due and the current wallet balance. An invoice can combine multiple payment sources (e.g. wallet + credit card), and this breakdown is displayed on the generated PDF invoice. Hyperline also records which wallet credits funded each consumption. It uses the oldest available funds first, so one invoice payment can consume the end of one top-up and part of the next. See [Understand payment allocations](/docs/payments/allocations#wallet-allocations) for an example and the relationship with payment allocations. ### Reverse a wallet payment Use **Reverse wallet payment** from an invoice when a wallet consumption should no longer pay that invoice. Hyperline cancels the wallet debit, returns the amount to the wallet balance, and recalculates the invoice. This is not the same as unallocating a standard transaction. Unallocating makes the amount available again on that transaction. Reversing a wallet payment makes the amount available again in the wallet because the wallet debit itself is cancelled. Reversing a wallet payment can make a previously paid invoice payable again. It does not reverse or refund the transaction that originally funded the wallet. ## Revert a wallet top-up You can revert wallet top-up transactions to remove funds that were previously added to a customer's wallet. Only top-up transactions (credit transactions) can be reverted. Debit transactions (consumption) cannot be reverted. ### How it works When you revert a wallet transaction: * The credited amount is deducted from the current wallet balance * If the transaction was a **free top-up**, the related credit note is voided * If the transaction was a **paid top-up**, the amount is deducted from the wallet balance. If you need to refund the initial banking transaction, you must do so outside of Hyperline ### Requirements A transaction can only be reverted if: * It is a top-up transaction (not a debit/consumption transaction) * It has not already been reverted * The wallet has sufficient balance to cover the reversal amount Make sure the wallet balance is sufficient before reverting a transaction. If the balance is too low, the revert action will fail. ## Wallet balance & projection Wallet balances are computed in real time in Hyperline. In addition to the wallet balance, Hyperline also computes and returns a projected balance. This balance takes into account a projection of the future remaining money on the wallet after paying what will be due in the current period (subscription, usage). This is particularly useful for pay-as-you-go use cases. For example, you can restrict access to your product when the customer doesn't have enough funds in their wallet. # Wallets overview Source: https://docs.hyperline.co/docs/wallets/overview Manage customer prepaid balances in Hyperline wallets: top up funds, auto-apply to invoices, and support upfront billing or pay-as-you-go flows. Hyperline wallets let you manage customer balance: prepaid funds that you or your customers can add and automatically apply when invoices are paid. This feature is particularly useful for setting up upfront payments in pay-as-you-go flows or offering free funds to your customers. Each customer can have their own wallet in their preferred currency. A wallet cannot have a negative balance. ## Wallet settings Configured at the account level (in the **Settings** > **Wallets** page), these settings apply to all customer wallets. By default, the wallet feature is disabled. To activate it, navigate to your settings. ### Free top-up This option allows you to add funds directly to your customers' wallets at no additional cost. When you add free funds to the wallet, Hyperline generates a corresponding credit note for accounting purposes. ### Top-up from customer portal This option allows your customers to add funds using their current payment method directly through their portal. An active and valid payment method is required for the top-up to be successful. ### Eligible products You can select the products to which you want the wallets to apply when paying invoices. By default, the wallets apply to all products (i.e., the full invoice amount). ## Create a wallet for a customer Now that you have enabled wallets on the settings page, you can create wallets for your customers in Hyperline. To do this, go to the **Customers** page in Hyperline's main menu. Navigate to the **Wallet** tab and click **Create wallet**. ## Manage wallet You can decide to edit the configuration of a customer wallet. Go to a customer page > **Wallet** tab > **Actions** > **Edit wallet**. ### Update name You can update the wallet name. Use this name to identify the wallet depending on your use case. This name appears on the final invoice when the wallet is used as a payment method to pay the invoice. ### Auto top-up You can set up an automatic top-up for a customer's wallet at a specified interval. Configure the amount, the interval, and the next top-up date for this automated fund addition. Funds are added to the existing wallet balance. ### Pause wallet You can pause the use of a wallet for a specific customer. Hyperline no longer uses a paused wallet to pay future invoices. You can reactivate the wallet at any time. ## Pay-per-use If your customers are paying depending on their use of your services, you can provide them with a wallet so they have an upfront payment solution. **Example** One API call costs your customer 1 cent. If you activate the wallet, your customer will be able to top up their wallet in advance. They can then pay upfront for as much as they want and use your services until their wallet balance runs out. ## Managing zero balances If you allow your customers to top up their wallets, consider a flow to warn them before their wallet balance reaches 0. This is especially relevant if reaching a zero balance interrupts their services. You can use [our webhooks](/developers/webhooks) to monitor wallet activity. # Getting started Source: https://docs.hyperline.co/guides/ai Connect Claude, ChatGPT, Cursor, and other AI assistants to Hyperline using MCP, the CLI, and reusable skills for common billing workflows. AI assistants can help you explore Hyperline, build integrations, and automate billing workflows. Hyperline supports several AI-friendly entry points depending on where your assistant runs and what it needs to do. ## Choose how your AI assistant works with Hyperline Connect assistants such as Claude, ChatGPT, Cursor, and VS Code to your Hyperline account through MCP. Use the agent-first CLI for terminal-based assistants and scripts. ## Reusable skills Skills are reusable instructions that help an AI assistant perform a specific Hyperline workflow reliably. They combine the exact API shape, required inputs, and caveats the assistant should respect. This section collects practical skills you can copy into your own AI assistant or agent workspace. | Skill | Use it for | | - | - | | [Create a subscription from a template](/guides/ai/create-subscription-from-template) | Create a subscription from a template while preserving template configuration. | | [Create an invoice](/guides/ai/create-invoice) | Create draft or payable invoices with explicit line items and status. | | [Create a quote from a template](/guides/ai/create-quote-from-template) | Create a quote from a quote template and optionally set custom properties on the subscription created from that template. | | [Build an insights report](/guides/ai/build-insights-report) | Answer revenue, invoice, subscription, and usage reporting questions. | | [Investigate a customer balance](/guides/ai/investigate-customer-balance) | Reconcile customer balances, invoices, wallets, credits, and payments. | | [Answer a billing question](/guides/ai/answer-billing-question) | Answer Hyperline billing questions with docs and read-only account checks. | | [Bulk update subscriptions](/guides/ai/bulk-update-subscriptions) | Plan, confirm, apply, and verify bulk subscription changes safely. | ## Next steps * Use [Hyperline MCP](/developers/ai/mcp) when your assistant supports MCP and needs to read or write Hyperline data. * Use [Hyperline CLI](/developers/ai/cli) when your assistant can run shell commands. * Copy a skill into your agent instructions when you want repeatable behavior for a known workflow. # Answer a billing question with AI Source: https://docs.hyperline.co/guides/ai/answer-billing-question AI skill that answers Hyperline billing questions by combining product documentation with read-only checks against your live account data. Use this skill when an AI assistant needs to answer a question about a billing workflow, a customer account state, or how to use Hyperline. ## Skill ```md theme={null} --- name: answer-billing-question description: Answer a Hyperline billing question using documentation and read-only data checks. Use when an agent needs to explain subscriptions, invoices, payments, quotes, usage, credits, wallets, analytics, custom properties, or API behavior. --- # Answer Billing Question Start with documentation. Use account data only when the answer depends on the customer's current state. ## Inputs Collect: - The user's question. - Environment: production or sandbox if account data is needed. - Relevant entity IDs, names, or URLs if the question is about a specific customer, subscription, invoice, quote, or product. ## Workflow 1. Classify the domain: subscriptions, invoices, payments, quotes, usage, credits, wallets, analytics, custom properties, integrations, or API. 2. Read the most relevant Hyperline documentation or API reference. 3. If the question depends on live data, run read-only MCP, CLI, or API calls to inspect the relevant records. 4. Answer directly. 5. Include links to the most relevant docs when they help the user act. 6. Separate confirmed facts from assumptions. ## Output Return: - Short answer first. - Then the explanation or steps. - Then docs links or checked records. - Then any caveats. ## Safety - Do not change account data while answering a question unless the user explicitly asks and confirms the exact action. - Do not expose internal implementation details. - Do not invent IDs, statuses, or product names. - If data is ambiguous, say what is ambiguous and ask for the missing identifier. ``` ## Related documentation Use Hyperline's AI-friendly documentation entry points. Learn the API basics. # Build an insights report with AI Source: https://docs.hyperline.co/guides/ai/build-insights-report AI skill for building revenue, invoice, subscription, and usage insights reports by querying Hyperline analytics and billing data. Use this skill when an AI assistant needs to answer a reporting question such as MRR, ARR, revenue movement, invoice health, overdue invoices, or subscription trends. ## Skill ```md theme={null} --- name: build-insights-report description: Build a Hyperline billing or revenue insights report. Use when an agent needs to answer reporting questions with read-only API, MCP, or CLI calls across analytics, subscriptions, invoices, customers, and usage data. --- # Build Insights Report Default to read-only operations. ## Inputs Collect these values before querying data: - Report question: what the user wants to know. - Timeframe: e.g. current month, previous quarter, last 12 months. - Environment: production or sandbox. - Optional filters: customer, plan, product, currency, subscription status, invoice status, or segment. - Output format: short answer, table, CSV-ready data, or executive summary. If the timeframe is ambiguous, ask a short clarification before querying. ## Data sources Start with the narrowest source: - `GET /v1/analytics` for revenue metrics and high-level KPIs. - `GET /v2/subscriptions` for subscription lists, statuses, plans, renewal dates, and quote links. - `GET /v1/invoices` for invoice status, due dates, amounts, and payment health. - `GET /v2/customers/{id}` or `GET /v2/customers` for customer context. - Usage endpoints when the question is about usage-based billing or consumption. Use MCP or CLI equivalents when the user's agent environment already has them configured. ## Workflow 1. Restate the metric definition in one sentence. 2. Query only the data needed for that definition. 3. Use pagination for list endpoints. 4. Keep raw IDs in working notes, but present names and links when available. 5. Separate facts from interpretation. 6. Call out gaps, filters, or assumptions. ## Output Return: - Answer first. - Then a small table when it helps. - Then methodology: endpoints, filters, and timeframe. - Then caveats or recommended follow-up. ## Safety - Do not mutate data. - Do not infer cash collection from invoice issuance; check payment or transaction status when the question is about cash. - Do not mix sandbox and production data. - Do not compare periods with different currencies unless the user asked for a multi-currency view. ``` ## Related documentation Use analytics metrics for high-level reporting. Learn how Hyperline analytics are organized. # Bulk update subscriptions with AI Source: https://docs.hyperline.co/guides/ai/bulk-update-subscriptions AI skill for planning, confirming, applying, and verifying bulk subscription updates in Hyperline without breaking customer billing. Use this skill when an AI assistant needs to update many subscriptions with the same change, such as adding a product, changing pricing, or transitioning subscriptions to a new configuration. ## Skill ```md theme={null} --- name: bulk-update-subscriptions description: Plan and execute safe bulk subscription updates in Hyperline. Use when an agent needs to identify subscriptions, preview or apply transitions, update subscriptions, and verify results across many records. --- # Bulk Update Subscriptions Bulk updates can affect billing and invoices. Plan first, execute only after explicit confirmation. ## Inputs Collect these values before making changes: - Target cohort: filters, customer list, subscription IDs, plan, product, status, or segment. - Desired change: product, price, phase, template, billing behavior, or contract change. - Effective date: immediately or scheduled date. - Billing behavior: no charge, pro-rata charge, custom charge, or keep current billing cycle. - Dry-run requirement: default to preview or sample first. ## Workflow 1. List candidate subscriptions using read-only filters. 2. Show the count and a small sample. 3. Ask the user to confirm the exact cohort before mutation. 4. Choose the safest update method: - Use `PUT /v2/subscriptions/{id}` for simple full-subscription updates with no transition invoice. - Use `POST /v2/subscriptions/transitions` when billing behavior, schedule, or pro-rata handling matters. - Use template-based transition only when subscriptions still match the source template and the template has already been updated. 5. Preview where possible. 6. Apply in bounded batches. 7. Verify updated subscriptions and summarize successes and failures. ## Safety - Never run an unbounded update. - Never mutate before showing the matched cohort and receiving confirmation. - Do not use deprecated incremental update endpoints. - Do not assume no invoice will be generated; choose and document the billing behavior. - Stop on repeated failures and summarize the partial result. ## Output Return: - Cohort definition. - Update method. - Billing behavior. - Batch result summary. - Failed subscription IDs with errors. - Verification checks performed. ``` ## Related documentation Learn the supported bulk update patterns. Use transitions for controlled subscription changes. # Create an invoice with AI Source: https://docs.hyperline.co/guides/ai/create-invoice AI skill for creating draft or payable Hyperline invoices through the public API with explicit line items, customer, currency, and status. Use this skill when an AI assistant needs to create an invoice with one or more line items through the public API. ## Skill ````md theme={null} --- name: create-invoice description: Create a Hyperline invoice through the public API. Use when an agent needs to draft or execute a POST /v1/invoices payload with customer_id, explicit status, line_items, payment settings, and optional custom properties. --- # Create Invoice Use the public API endpoint `POST /v1/invoices`. ## Inputs Collect these values before calling the API: - `customer_id`: Hyperline customer ID. - `status`: usually `draft` or `to_pay`. - `line_items`: at least one line item. - Optional `currency`, `subscription_id`, `due_at`, `emitted_at`, `payment_method_strategy`, `custom_properties`, `purchase_order`, and invoice notes. If the user gives product names instead of IDs, resolve product IDs first. Do not guess. ## Payload Draft invoice with a catalog product: ```json { "customer_id": "cus_xxx", "status": "draft", "line_items": [ { "product_id": "prod_xxx", "units_count": 1, "unit_amount": 10000, "tax_rate": 20 } ] } ``` Draft invoice with an ad hoc line item: ```json { "customer_id": "cus_xxx", "status": "draft", "currency": "EUR", "line_items": [ { "name": "Implementation fee", "unit_amount": 50000, "units_count": 1, "tax_rate": 20 } ] } ``` Call shape: ```bash curl -X POST "https://api.hyperline.co/v1/invoices" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '' ``` ## Safety - Always set `status` explicitly. Use `draft` unless the user clearly wants the invoice issued. - Do not set `paid` unless the user explicitly says the invoice is already paid. - Use `payment_method_strategy: "external"` only when payment is handled outside Hyperline. - Include `subscription_id` only when the invoice should be linked to an existing subscription. ## Verify After creation: 1. Read `id`, `status`, `customer_id`, `amount_excluding_tax`, and `amount_including_tax` from the response. 2. Fetch `GET /v1/invoices/{id}` if you need to confirm line items. 3. If the invoice should be sent or charged, ask for explicit confirmation before taking the next action. ```` ## Related documentation See the public API endpoint for creating invoices. Learn how invoices work in Hyperline. # Create a quote from a template with AI Source: https://docs.hyperline.co/guides/ai/create-quote-from-template AI skill for creating a Hyperline quote from a template while preserving terms, attachments, contract documents, and optional draft subscription updates. Use this skill when an AI assistant needs to create a quote from an existing quote template through the public API. The quote template provides the quote defaults, terms, attachments, contract documents, and subscription configuration. You can optionally update the draft subscription created from the template after the quote has been created. ## Skill ````md theme={null} --- name: create-quote-from-template description: Create a Hyperline quote from a quote template through the public API while preserving template terms, attachments, and contract documents. Use when an agent needs to draft or execute a quote from template workflow, optionally updating subscription custom properties, dates, products, phases, coupons, discounts, prices, or seats on the draft subscription after creation. --- # Create Quote From Template Use the public API endpoint `POST /v1/quotes`. ## Inputs Collect these values before calling the API: - `customer_id`: Hyperline customer ID. - `template_id`: quote template ID. - Optional `custom_properties`: key/value map using custom property slugs as keys. - Optional subscription overrides such as contract dates, products, phases, coupons, discounts, prices, or seats. - Optional quote-level overrides such as `owner_email`, `expires_at`, `status`, display fields, or collection requirements. If the user gives custom property names instead of slugs, resolve or ask for the slug first. Do not guess. ## Payload Use one call only when the quote should stay exactly on the template subscription configuration, with at most subscription custom properties or trial values. Minimal quote from template: ```json { "customer_id": "cus_xxx", "template_id": "quot_xxx" } ``` Quote from template with subscription custom properties: ```json { "customer_id": "cus_xxx", "template_id": "quot_xxx", "subscription": { "custom_properties": { "sales_segment": "enterprise", "requires_procurement": true, "renewal_owner": "finance", "tags": ["strategic"], "legacy_ref": null } } } ``` Call shape: ```bash curl -X POST "https://api.hyperline.co/v1/quotes" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '' ``` ## Subscription overrides If the user needs subscription overrides such as contract dates, products, phases, coupons, discounts, prices, or seats, use two calls: 1. Create the quote from the template with `POST /v1/quotes`. ```json { "customer_id": "cus_xxx", "template_id": "quot_xxx" } ``` 2. Read `id` and `subscription_id` from the quote response, then update the draft quote subscription with `PATCH /v1/quotes/{id}`. ```json { "subscription": { "custom_properties": { "sales_segment": "enterprise" }, "contract_start": "2026-07-08T00:00:00Z", "phases": [ { "activation_strategy": "start_date", "starts_at": "2026-07-08T00:00:00Z", "end_strategy": "duration", "duration": { "period": "months", "count": 6 }, "billing_date_setting": "phase_start", "products": [], "coupons": [] } ] } } ``` Do not send `terms`, `comments`, or `contract_clause_ids` in the update unless the user explicitly wants to override template content. ## Behavior - `template_id` makes Hyperline create the quote from the quote template. - The quote template supplies the subscription configuration from its linked subscription template or plan. - `subscription.custom_properties` applies values to the draft subscription created from the template. - Provided custom property slugs are updated. Omitted custom properties are left as-is. `null` clears that specific custom property. - Custom property values belong to the subscription, not the quote. - Updating the draft quote with a subscription payload replaces the draft subscription configuration while keeping the quote-level template content created in the first call. ## Do not accidentally replace the template subscription Keep `subscription` limited to `custom_properties` and, if needed, `trial`. Never send `subscription.products` or `subscription.phases` together with `template_id` in the initial `POST /v1/quotes` call. Those fields switch the request into custom subscription mode instead of taking the subscription configuration from the template, which can skip template terms, contract clauses, or contract documents. Other subscription fields are not reliable overrides in pure template mode. If the user needs purchase order, contract dates, products, phases, coupons, discounts, prices, or seats changed, create from the template first, then update the draft quote subscription with `PATCH /v1/quotes/{id}`. ## Quote custom property collection Do not confuse these fields: - `subscription.custom_properties`: values to set on the created subscription. - `collect_custom_property_ids`: quote signature flow asks the customer to fill customer custom properties by ID. Use `collect_custom_property_ids` only when the user wants the signer to provide customer custom properties during signature. ## Verify After creation: 1. Read `id`, `subscription_id`, `terms`, and `attachments` from the quote response. 2. If subscription values were provided or changed, fetch `GET /v2/subscriptions/{subscription_id}`. 3. Confirm `custom_properties` contains the provided slug/value pairs when provided. 4. Confirm the quote still has the expected template terms and attachments before finalizing or sending. ```` ## Related documentation See the public API endpoint for creating quotes. Learn how quote templates work in Hyperline. # Create a subscription from a template with AI Source: https://docs.hyperline.co/guides/ai/create-subscription-from-template AI skill for creating a Hyperline subscription from a subscription template while preserving the template's billing configuration. Use this skill when an AI assistant needs to create a subscription from an existing subscription template through the public API. ## Skill ````md theme={null} --- name: create-subscription-from-template description: Create a Hyperline subscription from a subscription template through the public API. Use when an agent needs to draft or execute a POST /v2/subscriptions payload with customer_id and template_id while preserving the template configuration. --- # Create Subscription From Template Use the public API endpoint `POST /v2/subscriptions`. ## Inputs Collect these values before calling the API: - `customer_id`: Hyperline customer ID. - `template_id`: subscription template ID. - Optional `template_configuration_id`: use only when the user knows the exact template configuration to apply. - Optional `checkout_session`: use only when the user wants to send a checkout session. If the user gives customer or template names instead of IDs, resolve them first. Do not guess. ## Payload Minimal subscription from template: ```json { "customer_id": "cus_xxx", "template_id": "subt_xxx" } ``` With an explicit template configuration: ```json { "customer_id": "cus_xxx", "template_id": "subt_xxx", "template_configuration_id": "stc_xxx" } ``` Call shape: ```bash curl -X POST "https://api.hyperline.co/v2/subscriptions" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '' ``` ## Behavior - `template_id` without `products` or `phases` creates the subscription from the template. - If `template_configuration_id` is omitted, Hyperline resolves the applicable configuration from the customer details. - The created subscription inherits the template's products, phases, billing rules, and pricing. ## Do not accidentally create a custom subscription Do not send `products` or `phases` unless the user explicitly wants a custom subscription configuration. Those fields create a custom subscription and only reference the template for reporting. If the user wants to change prices, products, phases, coupons, or billing cadence, confirm whether they want to update the template first or create a custom subscription payload. ## Verify After creation: 1. Read `id`, `status`, `customer_id`, and `template_id` from the response. 2. Fetch `GET /v2/subscriptions/{id}` if you need to confirm products or phases. 3. Confirm the subscription belongs to the intended customer. ```` ## Related documentation See the public API endpoint for creating subscriptions. Learn how subscription templates work in Hyperline. # Investigate a customer balance with AI Source: https://docs.hyperline.co/guides/ai/investigate-customer-balance AI skill for reconciling a Hyperline customer's balance across their invoices, wallet, credits, payments, and outstanding transactions. Use this skill when an AI assistant needs to explain why a customer balance looks wrong or reconcile what a customer owes. ## Skill ```md theme={null} --- name: investigate-customer-balance description: Investigate a Hyperline customer balance with read-only checks. Use when an agent needs to reconcile customer balance, open invoices, wallet or credit balances, invoice payments, refunds, and recent transactions. --- # Investigate Customer Balance Default to read-only operations. ## Inputs Collect these values before querying data: - Customer ID, external ID, or customer name. - The balance question: outstanding amount, credit balance, wallet balance, payment mismatch, refund, or invoice status. - Timeframe if relevant. - Environment: production or sandbox. If the user gives a name, resolve the customer and confirm when multiple customers match. ## Workflow 1. Get the customer record. 2. List recent invoices for the customer. 3. Check invoice statuses, due dates, totals, outstanding amounts, and related transactions. 4. Check wallet balances and wallet transactions when the question mentions prepaid balance, wallet, top-up, or credit. 5. Check credit balances and credit transactions when the question mentions credits or usage credits. 6. Compare the expected balance against the sum of open invoices, payments, refunds, wallet movements, and credit movements. ## Useful endpoints - `GET /v2/customers/{id}` for customer context. - `GET /v1/invoices` filtered by customer for invoices and status. - `GET /v1/invoices/{id}` for invoice details. - Wallet endpoints for wallet balance and transactions. - Customer credit endpoints for credit products and credit transactions. Use MCP or CLI equivalents when available. ## Output Return: - Direct answer first. - Then a short reconciliation table. - Then the records checked. - Then unresolved gaps or next checks. ## Safety - Do not mark invoices paid, void invoices, issue refunds, or load wallets without explicit confirmation. - Do not assume an invoice is paid because a payment exists; verify final invoice and transaction status. - Do not assume usage credits and wallet balance are the same thing. ``` ## Related documentation Retrieve customer details. Learn how customer balances are represented in Hyperline. # Run Hyperline on autopilot Source: https://docs.hyperline.co/guides/autopilot Use Sentinel, customer intelligence, usage tracking, notifications, exports, and AI assistants to reduce manual checks across revenue operations. Use this guide when you want Hyperline to surface the work that needs attention instead of relying on manual checks across customers, invoices, payments, subscriptions, integrations, and usage. Hyperline has several automation layers. They work best together. Sentinel monitors operational issues, and customer intelligence monitors customer signals. Notifications route findings to the right teammates, and AI assistants help investigate or execute repeatable workflows when you need more context. ## Choose the right automation layer | Need | Use | Start here | | - | - | - | | Detect billing or integration issues | Sentinel | [Sentinel monitoring](../docs/sentinel/overview) | | Monitor customer health, risk, and expansion signals | Customer intelligence | [Customer intelligence](../docs/customer-intelligence/overview) | | Review a specific set of customers automatically | Customer monitoring agents | [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent) | | Route customer updates to the right people | Owners, followers, and notifications | [Owner and followers](../docs/customer-intelligence/owner-followers) | | Track adoption, consumption, and product milestones | Custom usage tracking | [Custom usage tracking](../docs/customer-intelligence/custom-usage-tracking) | | Prioritize collections follow-up | Late payment behavior | [Late payment behavior](../docs/customer-intelligence/late-payment-behavior) | | Answer questions or run assisted workflows | Hyperline AI tools | [AI assistant setup](./ai) | ## What each layer does Watches billing operations and creates tasks for issues such as failed payments, late invoices, disconnected integrations, and subscription errors. Reviews customer context across usage, billing, payments, ownership, support, and communication signals. Shows custom usage metrics on customer records so teams can monitor adoption, consumption, and plan limits. Connects Hyperline to AI assistants through MCP, the CLI, and reusable workflow skills. ## Recommended setup ### 1. Start with Sentinel Use [Sentinel monitoring](../docs/sentinel/overview) for operational issues that should not depend on someone checking lists manually. Sentinel is useful for: * Failed or late payments * Draft or overdue invoices * Disconnected payment providers or integrations * Subscription renewal issues * Electronic invoicing failures Give the right teammates access to Sentinel tasks so operational issues reach the people who can resolve them. ### 2. Add customer intelligence Use [customer intelligence](../docs/customer-intelligence/overview) when you want to prioritize accounts based on customer context, not only billing exceptions. Customer intelligence can help you monitor: * Customers with payment risk or late payment patterns * Accounts with declining or growing usage * Strategic customers approaching renewal * Expansion opportunities based on adoption or consumption * Customers with weak communication or unresolved support signals Create a [customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent) from **Customers > Monitoring**. Start with **Autopilot** when you want Hyperline to choose the schedule and signal weighting. Use **Advanced** mode when you want to focus the agent on a specific segment or workflow. ### 3. Route findings to owners and followers Assign [owners and followers](../docs/customer-intelligence/owner-followers) so customer findings have a clear audience. Use this when: * Account owners should receive customer health findings * Finance teammates should follow payment-risk segments * Customer success managers should follow strategic accounts * Managers need visibility without becoming the customer owner Each teammate can also manage their notification channels from **Profile > Notifications**. ### 4. Expose usage signals Use [custom usage tracking](../docs/customer-intelligence/custom-usage-tracking) to display product-specific metrics on customer records. Good usage metrics include: * Seats used * API calls * Storage consumed * AI credits spent * Active workspaces * Feature adoption milestones These signals help teams spot adoption risk, upsell readiness, and customers approaching plan limits. ### 5. Connect AI assistants for deeper workflows Use [Hyperline AI tools](./ai) when an assistant needs to investigate, explain, or prepare repeatable revenue workflows. For example, an assistant can help: * Investigate a customer balance * Build an insights report * Answer a billing question * Draft a quote or invoice workflow * Plan a bulk subscription update Use [Hyperline MCP](../developers/ai/mcp) when your assistant supports MCP, or [Hyperline CLI](../developers/ai/cli) for terminal-based assistants and scripts. ## Example workflows | Workflow | Hyperline setup | | - | - | | A payment provider disconnects | Sentinel creates a task and links to the affected integration. | | A strategic customer has declining usage before renewal | A monitoring agent reviews the customer, combines usage and account context, and can notify the owner. | | A finance team wants to prioritize collections | Create a late payment behavior segment, follow the segment, and use Sentinel for invoice-level payment issues. | | A customer is approaching an AI credit limit | Display the credit or usage metric on the customer record and use customer intelligence to surface expansion context. | | A manager wants a weekly revenue review | Use analytics, exports, and AI assistant workflows to summarize subscriptions, invoices, payments, usage, and customer signals. | ## Next steps * Configure [Sentinel monitoring](../docs/sentinel/overview) for operational issue detection. * Create a [customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent) for strategic customer segments. * Set up [owners and followers](../docs/customer-intelligence/owner-followers) so findings reach the right teammates. * Connect [AI assistants](./ai) for assisted investigation and repeatable workflows. # Bulk update subscriptions Source: https://docs.hyperline.co/guides/bulk-update-subscriptions Bulk update Hyperline subscriptions through the API: add products, change prices, or adjust contracts on many subscriptions in a single workflow. Sometimes you need to apply the same change to multiple subscriptions, such as adding a new product to all customers. You have several options depending on your use case and requirements. ## Overview of methods | Method | Best for | Pros | Cons | | - | - | - | - | | [Update full subscription](#update-full-subscription) | Simple bulk updates with no pro-rata invoicing | Versioning, no transition invoice, keeps billing cycle | — | | [Create a subscription transition](#create-a-subscription-transition) | Full control with versioning and billing options | Version history, flexible configuration | Advanced setup | | [Incremental update (deprecated)](#incremental-update-deprecated) | Legacy use cases | Simple | No versioning, not future-proof | ## Update full subscription **Recommended for most bulk update scenarios.** The `PUT /v2/subscriptions/:id` endpoint performs an immediate transition while keeping the billing cycle and waiving the transition invoice. This means no pro-rata invoice is generated. You want to add a new "Support" product to all active subscriptions. Using this method, the product is added immediately without generating pro-rata charges, and customers continue on their existing billing cycle. ### How it works 1. Fetch the subscription using `GET /v2/subscriptions/:id` to get its current configuration 2. Add the new product to the subscription phases 3. Call `PUT /v2/subscriptions/:id` with the full updated subscription payload The payload structure matches the response from `GET /v2/subscriptions/:id`, allowing you to retrieve a subscription, modify it, and update it using the same structure. ```sh theme={null} curl -X PUT "https://api.hyperline.co/v2/subscriptions/{subscription_id}" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "phases": [ { "id": "phase_xxx", "products": [ ... { "product_id": "prod_new_product_id", "price": { "type": "flat_fee", "amount": 1000, "interval": "month" } } ], ... } ], ... // Existing subscription payload }' ``` ### When to use * Adding a product to multiple subscriptions without pro-rata billing * Making simple configuration changes across subscriptions * When you want version history with minimal configuration ## Create a subscription transition Use the transition endpoint when you need full control over the update process, including billing options. ### Option A: Pass the full subscription configuration Call `POST /v2/subscriptions/transitions` with the source subscription and target subscription configuration including the new product. ```sh theme={null} curl -X POST "https://api.hyperline.co/v2/subscriptions/transitions" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "source_subscription_id": "sub_xxx", "application_schedule": "immediately", "billing_cycle_transition_method": "keep_current_billing_cycle", "calculation_method": "do_not_charge", "target_subscription": { "phases": [ { "products": [ ... ], ... } ], ... // Existing subscription payload } }' ``` ### Option B: Transition to an updated template/plan Use this option if you created the subscription from a template or plan and **have not customized it since**. If you've already updated that template/plan with the new product, you can transition the subscription to use the updated template. You have 100 customers on the "Pro Plan" template. You add a new "Analytics" product to the Pro Plan template. Instead of specifying the full subscription configuration for each customer, you transition each subscription to the updated Pro Plan template. ```sh theme={null} curl -X POST "https://api.hyperline.co/v2/subscriptions/transitions" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "source_subscription_id": "sub_xxx", "application_schedule": "immediately", "billing_cycle_transition_method": "keep_current_billing_cycle", "calculation_method": "do_not_charge", "target_subscription": { "subscription_template_id": "template_xxx" } }' ``` This approach is efficient when many subscriptions share the same template, as you only need to pass the template ID rather than the full subscription configuration. ### Transition options | Parameter | Description | | - | - | | `application_schedule` | When to apply: `immediately` or `scheduled` (with `transition_date`) | | `billing_cycle_transition_method` | `keep_current_billing_cycle` to keep current billing dates, `align_to_new_billing_cycle` to reset | | `calculation_method` | `do_not_charge` to skip transition invoice, `pro_rata` to generate pro-rata invoice | ## Incremental update (deprecated) The `POST /v1/subscriptions/:id/update-many` endpoint is deprecated. It lacks versioning and is not future-proof. Use one of the methods above instead. This endpoint allows updating multiple aspects of a subscription in a single call but does not maintain version history. ## Scripting bulk updates To update multiple subscriptions, write a script that: 1. Lists all target subscriptions using `GET /v2/subscriptions` with appropriate filters 2. For each subscription, applies the update using your chosen method 3. Handles errors and retries as needed Use pagination and rate limiting in your script. See the [rate limiting documentation](/developers/rate-limiting) for details. Is something still unclear? Don't hesitate to reach out to our team via the in-app chat if you need additional support. # Configure usage-based billing Source: https://docs.hyperline.co/guides/configure-usage-based-billing Step-by-step guide to set up your first usage-based subscription in Hyperline: events, aggregators, products, pricing tiers, and customer assignment. This guide walks you through setting up a complete usage-based billing workflow in Hyperline, from connecting your data to monitoring customer consumption. By the end, you'll have a working usage-based subscription with real-time usage tracking. ## Context You want to bill customers based on their actual consumption of your product or service, such as API calls, compute hours, storage, or any other measurable metric. This guide shows you how to configure this end-to-end using Hyperline's interface. ## Prerequisites Before you begin, make sure you have: * Access to your Hyperline account (we recommend using [test mode](../docs/getting-started/sandbox) for this setup) * Usage data ready to import, or the ability to generate simulated data for testing * A clear understanding of what metric you want to bill (e.g., API calls, GB stored, hours used) Once you've signed up, you can use the [test mode](../docs/getting-started/sandbox) to experiment before going live. ## Steps ### 1. Connect your usage data Hyperline needs usage data to calculate charges for usage-based products. You have three options to connect your data: Upload historical data from a CSV file Send events programmatically via API Connect directly to your database For testing purposes, you can skip this step initially and use [simulated events](../docs/usage/simulate-usage-data) directly in test mode. #### Using data loaders (recommended) Data loaders allow you to pull usage data directly from your database without writing code. This is ideal for connecting to existing data sources like PostgreSQL, BigQuery, MongoDB, or Snowflake. Go to the [data loaders page](https://app.hyperline.co/app/events/loaders) in Hyperline. Click **New connection** and select your database provider from the list. Fill in your database connection information: * Host and port * Database name * Authentication credentials * SSL settings (if required) After connecting, create a new data loader with a SQL query that returns: * `timestamp`: The date and time of the event * `customerId`: Your customer's unique identifier * `id`: The event's unique identifier * Any additional fields you want to track (e.g., `quantity`, `region`, `product_type`) Test your query to ensure data is flowing correctly, then activate the data loader. Learn more about configuring data loaders in our detailed guides: * [BigQuery](../docs/usage/bigquery) * [MongoDB](../docs/usage/mongodb) * [Snowflake](../docs/usage/snowflake) * [General data loaders](../docs/usage/usage-data-with-connectors) ### 2. Create a usage-based product Once your events are flowing into Hyperline, you can create a product that bills based on this usage. Go to [**Products**](https://app.hyperline.co/app/products) and click **New product**. Select **Usage** as the product type. Fill in the basic product information: * **Name**: A descriptive name for your product (e.g., "API Calls", "Storage GB") * **Description**: Optional details about what this product represents Connect your product to the usage data you want to bill by selecting an [aggregator](../docs/usage/aggregators). If you haven't created one yet, head to **Usage > Aggregators** first. For billing, you link the aggregator to the product and then add that product to a subscription. You do not need to assign the aggregator directly to the customer in its **Visibility** settings. Direct assignment without a subscription is a separate monitoring workflow available with the Customer Intelligence module, and it does not generate charges. The aggregator defines: * **Event type**: Which events to aggregate * **Operation**: How to calculate usage: * **Count**: Count the number of events * **Sum**: Add up a specific numeric property * **Filters**: Optional conditions to narrow eligible events Set up your pricing model: * **Pricing model**: Select one of: * **Volume pricing**: Price per unit changes based on total usage * **Bulk pricing**: All units charged at the rate of the tier reached * **Basis points**: Percentage-based pricing * **Price tiers**: Define your pricing tiers and amounts * Example: $0.10 per unit for 0-1,000 units, $0.08 per unit for 1,001-10,000 units * **Billing interval**: Set when this product should be billed (monthly, quarterly, yearly) Make sure to configure at least one recurring price before moving to the next step. Click **Save** to add the product to your catalog. You want to charge for API calls with volume pricing: * 0-10,000 calls: \$0.01 per call * 10,001-100,000 calls: \$0.008 per call * 100,001+ calls: \$0.005 per call Create a "Count" aggregator on your API event type, link it to your usage product, then set up three pricing tiers with these rates. For detailed information on metering configuration options, see our [usage-based products guide](../docs/subscriptions/metering). ### 3. Create a customer Before assigning a subscription, you need a customer in Hyperline. Navigate to [**Customers**](https://app.hyperline.co/app/customers) and click **New Customer**. Enter the required information: * **Name**: Customer or company name * **Currency**: The currency for billing this customer * **Country**: Customer's country (used for tax calculations) You can add additional details like email, address, and tax information, or update them later. Click **Save customer** to create the customer record. Learn more about customer management in our [customer creation guide](../docs/customers/overview). ### 4. Configure a subscription with the usage product Now you'll create a subscription that includes your usage-based product. From your customer's page, click **Actions** → **Assign new subscription**. Alternatively, go to [**Subscriptions**](https://app.hyperline.co/app/subscriptions/create) and select your customer. Configure when the subscription starts: * **Immediately**: Start billing right away * **In the future**: Schedule for a specific date * **On checkout completion**: Wait for customer to complete checkout Click **Add product** and select the usage-based product you created earlier. Configure the product settings: * **Pricing**: Select or customize the pricing tier * **Metering period**: Select when usage is measured: * **Same as payment interval**: Usage resets each billing cycle * **Current contract period**: Usage measured over the entire contract * **Custom**: Define a specific metering window * **Min/max amounts**: Optionally set spending limits per billing period * **Committed units**: Set minimum usage commitments if needed (customer pays for at least X units) Click **Next** to access payment settings. For testing purposes, select **Manually later** to create the subscription without immediate payment. For production, select: * **Checkout page**: Customer completes payment via Hyperline checkout * **Immediately**: Charge the customer's default payment method Click **Assign subscription** to activate it. Hyperline redirects you to the customer page, where you can see the subscription and current usage. A customer subscribes to your API product with monthly billing. They have a committed minimum of 5,000 API calls per month (they'll be charged for at least 5,000 calls even if they use fewer). They also have a maximum spending cap of \$500 per month to prevent unexpected bills. For more details on subscription configuration options, see our [subscription setup guide](../docs/subscriptions/create). ### 5. Simulate usage (optional, for testing) If you're in [test mode](../docs/getting-started/sandbox), you can simulate usage events to see how billing works without real data. From your customer's page, click the **Events** tab. Click the **Simulate new events** button at the top of the events list. Fill in the details: * **Event type**: Use the same event type configured in your product * **Date**: Select when the events occurred (must be within the current billing period) * **Number of events**: How many events to create * **Payload** (optional): Add custom event properties in JSON format ```json theme={null} { "quantity": 100, "region": "us-east-1" } ``` Click **Create new events**. The events appear in the customer's event list after a few seconds. You can delete simulated events at any time if you need to reset your test data. This is only available in test mode. Learn more about simulating usage in our [simulate usage data guide](../docs/usage/simulate-usage-data). ### 6. Monitor usage and understand open invoices After creating usage events, you can track consumption and preview upcoming charges. #### View current usage From the customer's **Subscriptions** tab, you'll see the current usage displayed next to each usage-based product. Click the eye icon next to the unit count to open the consumption details modal, which shows: * Total usage for the current billing period * Individual events contributing to the usage * Calculated amount based on your pricing tiers * Breakdown by time period or event properties For detailed usage analysis and exports, see our [explore usage consumption guide](../docs/usage/explore-usage-consumption). #### Understanding open invoices An **open invoice** is a live preview of the invoice that will be charged at the end of the billing period. For usage-based subscriptions, this invoice updates automatically in real-time as new usage events are recorded. **Key characteristics of open invoices:** * **No invoice number yet**: Open invoices don't have a final invoice number because they're still being calculated * **Cannot be paid**: Customers cannot pay an open invoice. It's for preview purposes only * **Updates in real-time**: As usage accumulates, the invoice amount increases automatically * **Visible to customers**: Customers can see their open invoice in the [customer portal](../docs/customers/portal) to track their current charges **To view an open invoice:** 1. Go to the customer's **Invoices** tab 2. Look for the invoice with status `open` 3. Click the invoice to see the current charges and line items A customer subscribes on January 1st with monthly billing. An open invoice is immediately created for the January 1-31 period. As they make API calls throughout the month, the invoice updates: * January 5: 2,500 calls → Invoice shows \$25 * January 15: 8,000 calls → Invoice shows \$80 * January 31: 15,000 calls → Invoice shows \$138 (with tiered pricing) On February 1st, the invoice enters the grace period for final review. #### Invoice lifecycle for usage-based billing Usage-based invoices follow this lifecycle: 1. **Open**: Invoice is created at the start of the billing period and updates as usage accumulates 2. **Grace period**: At the end of the billing period, the invoice enters a grace period (default: 3 days). During this time, you can review and make manual adjustments if needed 3. **To pay**: After the grace period, the invoice is finalized with an invoice number and sent for payment 4. **Paid**: Payment is collected and the invoice is settled During the grace period, you can still make adjustments to the invoice (add credits, apply discounts, etc.). Once the grace period ends, Hyperline locks the invoice and you can't modify it. You can configure the grace period duration in **Settings** → **Invoicing**. Learn more about [invoice terms and grace periods](../docs/invoices/term). ## Next steps You've successfully set up a usage-based subscription! Here are some ways to expand your implementation: View detailed usage reports and export data Learn about advanced metering configurations Update, pause, or cancel subscriptions Customize invoice templates and settings Is something still unclear? Don't hesitate to reach out to our team via the in-app chat if you need additional support. # Set up credit-based billing for an AI platform Source: https://docs.hyperline.co/guides/credit-based-billing-ai Implement credit-based billing for an AI platform: configure credit products, weighted consumption across multiple models, and customer top-ups. This guide walks you through setting up a complete credit-based billing system in Hyperline. Customers purchase credits and consume them at different rates depending on which AI model they use. ## Context You run an AI platform that offers access to multiple LLM models with different capabilities and costs. Rather than billing per token for each model separately, you want to sell credit packs that customers can spend across all models. More powerful models consume more credits per usage. Your platform offers three model tiers: | Model | Use case | Credits per 1,000 tokens | | - | - | - | | `nova-fast` | Quick tasks, high volume | 1 | | `nova-pro` | Balanced performance | 4 | | `nova-ultra` | Complex reasoning | 15 | A customer with 10,000 credits could use them flexibly: heavy usage of the budget model, occasional use of the premium model, or any combination. ## Prerequisites Before you begin, make sure you have: * Access to your Hyperline account (we recommend using [test mode](../docs/getting-started/sandbox) for this setup) * An [API key](../developers/authentication) to send usage events * A clear understanding of the models you want to bill and their relative cost ratios Once you've signed up, you can use the [test mode](../docs/getting-started/sandbox) to experiment before going live. ## Steps ### 1. Send usage events via the API Every time a customer uses one of your models, your backend should send a billable event to Hyperline with the model name and the number of tokens consumed. ```sh theme={null} curl -X POST https://ingest.hyperline.co/v1/events \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "events": [ { "customer_id": "cus_xxxxxxxxxxxxx", "event_type": "llm_token_usage", "timestamp": "2026-03-25T14:30:00Z", "properties": { "model": "nova-pro", "tokens": 1500 } } ] }' ``` Each event should include: * `customer_id`: the Hyperline customer ID (or `external_id` if you've mapped your internal IDs) * `event_type`: a consistent name for your token usage events (e.g., `llm_token_usage`) * `properties.model`: the model identifier used for the request * `properties.tokens`: the total number of tokens consumed (input + output) For testing, you can skip this step and use [simulated events](../docs/usage/simulate-usage-data) directly in test mode to generate fake usage data. Learn more about event ingestion in our [send usage data guide](../docs/usage/send-usage-data). ### 2. Create one aggregator per model Each model tier needs its own [aggregator](../docs/usage/aggregators) so that Hyperline can track consumption separately and apply a different credit weight to each. Go to [**Usage > Aggregators**](https://app.hyperline.co/app/events/aggregators) and create three aggregators: | Aggregator name | Event type | Operation | Property | Filter | | - | - | - | - | - | | `nova-fast tokens` | `llm_token_usage` | Sum | `tokens` | `model` = `nova-fast` | | `nova-pro tokens` | `llm_token_usage` | Sum | `tokens` | `model` = `nova-pro` | | `nova-ultra tokens` | `llm_token_usage` | Sum | `tokens` | `model` = `nova-ultra` | All three aggregators listen to the same `llm_token_usage` event type but use a filter on the `model` property to isolate each model's consumption. The **Sum** operation on `tokens` gives you the total number of tokens consumed per model. When a customer sends 3 requests to `nova-pro` consuming 1,200, 800, and 2,000 tokens respectively, the `nova-pro tokens` aggregator reports a total of 4,000 tokens for that period. ### 3. Create a credit product with weighted aggregators Now create a credit product that ties all three aggregators together with their respective weights. Go to [**Products**](https://app.hyperline.co/app/products), click **New product**, and select **Credit**. In the **Aggregators** section, add the three aggregators you just created and set the weight for each: | Aggregator | Weight | | - | - | | `nova-fast tokens` | 1 | | `nova-pro tokens` | 4 | | `nova-ultra tokens` | 15 | The weight determines how many credits are consumed per unit of usage. With these weights, 1,000 tokens on `nova-ultra` consumes 15 credits, while the same 1,000 tokens on `nova-fast` consumes only 1 credit. In the **Prices** section, configure your credit packs. For example: | Bundle size | Price | | - | - | | 10,000 credits | \$100 | | 50,000 credits | \$400 | | 200,000 credits | \$1,200 | These bundles will be available for purchase via the customer portal and auto-topup. Click **Save** to add the credit product to your catalog. For more details on multi-aggregator credit products, see the [credits overview](../docs/credits/overview#multiple-aggregators-with-weights). ### 4. Set up a credit balance on a customer With your credit product ready, enable a credit balance on a customer. Go to [**Customers**](https://app.hyperline.co/app/customers), select a customer, and click the **Credits** tab. Click **Add credit balance** and select the credit product you created. Configure the initial settings: * **Starting balance**: the number of credits to grant immediately (e.g., 10,000) * **Warning limit**: the threshold at which a low-balance warning appears on the customer portal (e.g., 1,000 credits) ### 5. Add the credit product to a subscription To automate credit replenishment and invoicing, add the credit product to a subscription. From the customer's page, click **Actions** > **Assign new subscription**, or open an existing subscription. Click **Add product**, select your credit product, and select a bundle pricing tier. To ensure your customer never runs out of credits, configure auto-topup on their credit balance: * **Threshold**: when the balance drops below this number, auto-topup triggers (e.g., 500 credits) * **Amount**: how many credits to add (e.g., 10,000) * **Pricing**: select a bundle price or set a custom amount Auto-topup automatically creates an invoice, charges the customer's payment method, and adds credits to their balance. Auto-topup requires the customer to have a valid payment method on file. If the payment fails, Hyperline doesn't process the topup. ### 6. Monitor consumption Once the customer starts using your models, you can track credit consumption from the customer's **Credits** tab. The **credits chart** shows balance evolution over time. Use the date range and granularity controls (day, week, month) to analyze consumption patterns. Click **All transactions** to view the full **transactions table**, which lists every credit movement: top-ups, usage deductions, and expirations. For multi-aggregator products, an **Aggregator** column shows which model triggered each usage transaction. Click **Explore** on any usage transaction to inspect and export the underlying consumption events. A customer starts the month with 10,000 credits. They make: * 2,000 `nova-fast` calls averaging 1,000 tokens each → 2,000 x 1 = **2,000 credits** * 300 `nova-pro` calls averaging 1,500 tokens each → 450 x 4 = **1,800 credits** * 50 `nova-ultra` calls averaging 2,000 tokens each → 100 x 15 = **1,500 credits** Total consumption: **5,300 credits**. Remaining balance: **4,700 credits**. The transactions table shows each deduction tagged with the corresponding aggregator, so you can see exactly which model is driving consumption. ## Next steps Learn more about credit products and configuration options Configure credits to expire after a set period or at the end of each billing cycle Let customers view their balance and purchase credits from the portal Manage credits programmatically via the API Is something still unclear? Don't hesitate to reach out to our team via the in-app chat if you need additional support. # Implement Hyperline for a self-serve product Source: https://docs.hyperline.co/guides/implement-self-serve Implement Hyperline for a self-serve SaaS product: signups, checkout, subscription lifecycle, and customer portal integration with your application. This guide shows you how to implement Hyperline subscriptions in the context of a self-serve product. ## Context You have a pricing page on your marketing website and want your customer to subscribe when clicking on an offer. ## Prerequisites 1. [Create a Hyperline account](https://app.hyperline.co/auth/signup) 2. Follow the steps to [configure your account](../docs/getting-started/configure-account) 3. A clear idea of the plans you want to sell and their associated prices 4. An [API key](../developers/authentication) to use the Hyperline API Once you've signed up, you can use the [test mode](../docs/getting-started/sandbox) to experiment before going live. ## Steps ### 1. Model your products and templates in Hyperline The first thing you need to do is to create your [products](../docs/products/overview) and (optionally) [subscription templates](../docs/subscriptions/templates) in Hyperline. You'll need to do this operation once, but you can easily iterate on your pricing to experiment and adjust later. If you need any assistance in finding the best way to represent your offer or need advice, you can contact support using the **Help** chat. ### 2. Implement a subscription flow Below is a suggested example of the flow to initiate a prospect's subscription to your product. Of course, this may vary based on your specific use case and product, and you can adjust it to suit your requirements. For this example, the prospect initially signs up for your product by creating an account on your side. When the prospect signs up, your backend [creates a customer](../api-reference/endpoints/customers/create-customer) on Hyperline related to the newly signed up customer on your system. ```sh theme={null} curl --request POST \ --url https://api.hyperline.co/v1/customers \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "name": "My customer", "currency": "EUR", "external_id": <(optional) ID of the customer in your system>, "available_payment_methods": <(optional) list of authorized payment methods> }' ``` Then you can [assign a subscription](../api-reference/endpoints/subscriptions/create-subscription) from the template (representing your plans/offers) selected by the customer. You need to use the ID corresponding to the template previously created, which you can find in Hyperline [templates](https://app.hyperline.co/app/subscriptions/templates) (next to the template name). This example creates a **dedicated checkout page** for your customer to fill in their billing details, add their payment method and subscribe. The subscription starts from the current date, and Hyperline redirects the customer to a specific URL on your side (`https://myservice.com/api/callback`) after completing the checkout. Use `checkout_session.redirect_url` to set the URL where Hyperline redirects the customer after checkout completion. ```sh theme={null} curl --request POST \ --url https://api.hyperline.co/v2/subscriptions \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "customer_id": , "template_id": "subt_ji3uPodOneXk6R", "starts_at": "2025-12-20T00:00:00Z", "activation_strategy": "checkout", "checkout_session": { "redirect_url": "https://myservice.com/api/callback" } }' ``` If you want to customize the quantity of products, you can use an additional parameter in the request body. ```json theme={null} { "products": [ { "id": "itm_4vea8Gj0a5HZr9", "count": 23 } ] } ``` After creating the subscription, you'll receive the hosted checkout page URL in `checkout_session.url` in the response payload. ```json theme={null} "checkout_session": { "status": "opened", "url": "https://billing.hyperline.co/checkout/che_hEUPdVG7IgjpW1" } ``` Redirect your customer to `checkout_session.url` for them to subscribe. When the customer completes checkout, Hyperline redirects them to the final URL on your side (previously configured when creating the subscription). The customer is now successfully **subscribed to your service**. You have the option to store this information on your end or entirely rely on Hyperline and retrieve the subscription status for the customer at any time. ```sh theme={null} curl --request GET \ --url https://api.hyperline.co/v1/customers/ \ --header 'Authorization: Bearer ' ``` ```json theme={null} { "id": "cus_Typ0px2W0aiEtl", "name": "My customer", "currency": "EUR", "subscriptions": [ { "id": "sub_0kIc7jrF7gV00V", "status": "active" } ] } ``` If you want to retrieve the quantity of the subscription products or the full details, you can use the subscriptions API. ```sh theme={null} curl --request GET \ --url https://api.hyperline.co/v2/subscriptions/ \ --header 'Authorization: Bearer ' ``` ```json theme={null} { "status": "active", "products": [ { "id": "itm_4vea8Gj0a5HZr9", "type": "seat", "count": 23 } ] // ... } ``` **That's it!** You can then proceed with your desired product flow. Hyperline automatically invoices your customer and charges their payment method according to the configuration of the created subscription. ### 3. Follow the subscription You can retrieve a unique portal link at any time for your customer to follow their subscription, edit their payment method, or download their invoices. We recommend adding a button in your product redirecting to this page for your customer to "manage billing". ```sh theme={null} curl --request GET \ --url https://api.hyperline.co/v1/customers//portal \ --header 'Authorization: Bearer ' ``` ```json theme={null} { "url": "https://..." } ``` You can also [follow and manage](https://app.hyperline.co/app/customers) your customers' subscriptions on Hyperline. # Importing historical data Source: https://docs.hyperline.co/guides/importing-historical-data Import customers, subscriptions, and invoices from another billing system into Hyperline, with API endpoints and best practices for migrations. When migrating to Hyperline from another billing system, you can import your historical data using batch API endpoints. This allows you to maintain continuity in your billing records, reporting, and customer history. **Dedicated import service available** This guide explains how to import historical data autonomously using our API. However, we also provide a dedicated service to help you migrate data from your existing billing system. If you'd prefer assistance with your migration, please contact us via the in-app chat or discuss this option with your sales contact. ## What you can import You can import the following data types: * **Customers**: Customer profiles with all associated metadata * **Subscriptions**: Active and historical subscriptions with their configuration * **Invoices**: Invoice records including PDF documents ## Prerequisites Before importing subscriptions and invoices, you must configure your product catalog in Hyperline. Products referenced in subscription and invoice imports must already exist in your Hyperline account. **Configure products first** Subscriptions and invoices might require valid Hyperline product identifiers in their import payloads. Create all necessary products in Hyperline before starting your data import, or the API will reject requests with unknown product references. You can create products through: * The Hyperline web application under **Catalog > Products** * The [Products API endpoints](/api-reference/endpoints/products/create-product) ## Import process overview The recommended import sequence is: 1. Configure your product catalog (required for subscriptions and invoices) 2. Import customers (required for subscriptions and invoices) 3. Import subscriptions with historical start dates 4. Import invoices with their PDF documents **Test in sandbox first** Always test your import process in the sandbox environment before importing production data. This allows you to validate your data mapping and identify any issues without affecting live operations. Note that sandbox is not a clone of production. You'll need to seed it with a representative slice of customers and products to make the dry run meaningful. ## Importing customers Use the batch customer creation endpoint to import multiple customers at once (up to 50 per request). ```sh theme={null} curl -X POST https://api.hyperline.co/v1/customers/batch \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "customers": [ { "batch_customer_id": "batch_001", "name": "Acme Corporation", "billing_email": "billing@acme.com", "external_id": "cust_123_from_old_system" } ] }' ``` The `batch_customer_id` is required for batch operations to track each customer in the batch. **Look up customers by your old IDs** Set the `external_id` field to your previous system's customer ID, and you can resolve customers later via the API without maintaining a separate mapping table: ```sh theme={null} GET /v1/customers?external_id=cust_123_from_old_system ``` For detailed parameters and response format, see the [Create customers batch](/api-reference/endpoints/customers/create-customers-batch) endpoint documentation. ## Importing subscriptions You can create subscriptions with start dates in the past, allowing you to preserve historical subscription data. ### Key considerations for subscription imports * **Start date**: Set `starts_at` to the original subscription start date from your previous system * **Initial billing date**: Set `initial_billing_at` to the first or next date when Hyperline should start billing. This should typically be the next renewal date or the date when you want Hyperline to take over billing operations * **Activation strategy**: Use `start_date` to activate the subscription based on the `starts_at` date * **Contract terms**: Define contract duration and renewal settings * **Inactive subscriptions**: Import already-ended subscriptions only if you need them for historical reporting; otherwise skip them since they won't bill ```sh theme={null} curl -X POST https://api.hyperline.co/v2/subscriptions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "customer_id": "cust_hyperline_id", "activation_strategy": "start_date", "starts_at": "2023-01-15T00:00:00Z", "initial_billing_at": "2026-02-15T00:00:00Z", "contract_terms": { "activation_strategy": "start_date", "end_strategy": "duration", "duration": { "period": "years", "count": 1 }, "renew_automatically": true }, "products": [ { "id": "prod_hyperline_id", "payment_interval": { "period": "years", "count": 1 }, "payment_schedule": "start" } ] }' ``` The product `id` must reference a product that already exists in your Hyperline product catalog. Map your old system's products to Hyperline product IDs before importing subscriptions. A customer subscribed to your service on January 15, 2023, with annual billing. You're migrating to Hyperline in January 2026. Set `starts_at` to `2023-01-15` (preserving the original subscription start) and `initial_billing_at` to `2026-02-15` (the next renewal date when Hyperline should generate the invoice). For detailed parameters, see the [Create subscription](/api-reference/endpoints/subscriptions/create-subscription) endpoint documentation. ## Importing invoices Import historical invoices to maintain complete billing records and enable accurate reporting. ### Batch invoice creation Create multiple invoices at once (up to 50 per request): ```sh theme={null} curl -X POST https://api.hyperline.co/v2/invoices/batch \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "batch_id": "import_batch_2025_01", "invoices": [ { "batch_invoice_id": "inv_123_from_old_system", "customer_id": "cust_hyperline_id", "status": "paid", "emitted_at": "2025-01-15T00:00:00Z", "due_at": "2025-02-15T00:00:00Z", "settled_at": "2025-01-20T00:00:00Z", "line_items": [ { "product_id": "prod_hyperline_id", "name": "Annual subscription", "unit_amount": 12000, "units_count": 1 } ] } ] }' ``` The endpoint returns a `202 Accepted` response with a `batch_id` that you can use to track the batch processing: ```json theme={null} { "batch_id": "import_batch_2025_01" } ``` The batch invoice creation endpoint processes invoices asynchronously. See [Tracking batch invoice creation](#tracking-batch-invoice-creation) below for the webhook events you can listen to. The `batch_invoice_id` is required to track each invoice in the batch. Each line item should reference a `product_id` from your product catalog. For paid invoices, include the `settled_at` date to record when payment was received. For detailed parameters, see the [Create invoices](/api-reference/endpoints/invoices/create-invoices) endpoint documentation. Imported historical invoices do **not** generate [journal entries](/docs/accounting/entries) or [recognition schedules](/docs/accounting/revenue-recognition) on their own. The accounting module only posts for activity that happens after a ledger is created. If you need these invoices in your books, [contact our team](mailto:support@hyperline.co) once the import is complete and we can replay them into the ledger. ### Tracking batch invoice creation Since batch invoice creation is asynchronous, you should set up webhook listeners to track the success or failure of each invoice: * **`invoice.batch.creation_succeeded`**: Triggered when an invoice in the batch is successfully created * **`invoice.batch.creation_failed`**: Triggered when an invoice in the batch fails to be created Each webhook event includes the `batch_id` and `batch_invoice_id` to help you track which invoices were processed successfully. See the [Webhooks documentation](/developers/webhooks) for more details on setting up webhook endpoints. ### Importing invoice PDFs After creating an invoice record, you can upload the original PDF document from your previous system: ```sh theme={null} curl -X POST https://api.hyperline.co/v1/invoices/{invoice_id}/upload \ -H "Authorization: Bearer " \ -H "Content-Type: multipart/form-data" \ -F "file=@/path/to/invoice.pdf" ``` This preserves the original invoice formatting and branding from your previous system, which can be important for customer records and compliance. For detailed parameters, see the [Upload PDF to invoice](/api-reference/endpoints/invoices/upload-pdf-to-invoice) endpoint documentation. ## Best practices ### Data validation * Validate all data before importing to ensure it meets Hyperline's requirements * Check for required fields and data format compliance * Test with a small batch first to identify any mapping issues ### Batch size management * Process imports in batches of 50 items or fewer (API limit) * Implement retry logic for failed batches * Monitor API rate limits to avoid throttling ### Data mapping * Create a mapping document between your old system's data structure and Hyperline's * **Map products first**: Create a mapping between your old system's product IDs and Hyperline `product_id` values before importing subscriptions or invoices * Use `external_id` and `metadata` fields to maintain references to original system IDs * Document any data transformations or business logic applied during import ### Timing considerations * Schedule imports during low-traffic periods to minimize impact * Import customers before subscriptions and invoices (dependency order) * Allow time for data validation and reconciliation after import ### Date and timezone handling * Hyperline interprets all timestamps as UTC. Pass dates in ISO 8601 with an explicit offset (e.g. `2026-02-15T00:00:00Z`) * A bare date or local-time string can shift the billing day by ±1 in customer-facing invoices when your timezone differs from UTC * This matters most for `starts_at`, `initial_billing_at`, and the invoice `emitted_at` / `due_at` / `settled_at` fields. Pick the same calendar day your old system used and append `T00:00:00Z` ### Reconciliation After importing: * Verify customer counts match between systems * Reconcile subscription statuses and billing dates * Confirm invoice totals and payment statuses * Review reporting data to ensure accuracy **Irreversible operation** You can't automatically reverse data imports. Always test thoroughly in the sandbox environment before importing production data. Consider keeping backups of your original data until you've fully validated the import. # Keyboard shortcuts Source: https://docs.hyperline.co/guides/keyboard-shortcuts Move around Hyperline with keyboard shortcuts: search, create records, pull data from tables, and run operations without touching the mouse. Hyperline ships with keyboard shortcuts across navigation, search, record creation, and data tables. Most are wired in globally and work from anywhere in the app. The exception is when you're typing inside an input or editor, where the focused field captures the keys. On Mac, the modifier is `⌘`. On Windows and Linux, it's `Ctrl`. You type sequence shortcuts (e.g. `G` then `H`) in quick succession, with no modifier. ## Command palette The fastest way to do almost anything. | Shortcut | Action | | - | - | | `⌘ K` / `Ctrl K` | Open the command palette | | `Esc` | Close | | `↑` `↓` | Move between items | | `Enter` | Run the selected item | | `→` | Open a sub-menu | | `←` | Leave the current sub-menu | Paste any Hyperline entity ID (customer, subscription, invoice, product) into the palette to jump straight to its page. Useful when an ID lands in your inbox or in a Slack thread. ## Navigate: `G` then a letter Type `G`, then the destination letter(s), in quick succession. | Shortcut | Page | | - | - | | `G` `H` | Home | | `G` `C` `U` | Customers | | `G` `I` | Invoicing | | `G` `Q` | Quoting | | `G` `T` | Transactions | | `G` `R` | Reports | | `G` `E` | Events | | `G` `A` | Audit log | | `G` `C` `A` | Catalog | | `G` `S` | Settings | ## Create: `N` then a letter | Shortcut | Action | | - | - | | `N` `C` | New customer | | `N` `S` | New subscription | | `N` `Q` | New quote | Each shortcut opens the matching creation form as a modal, with no page reload and no lost context. ## Tables The new generation of Hyperline tables (currently Insights and Revenue recognition) supports spreadsheet-style selection. Select a few cells, copy, and paste straight into Excel, Google Sheets, or Notion. | Shortcut | Action | | - | - | | Click | Select a cell | | `Shift` Click | Extend selection to clicked cell | | `⌘` Click / `Ctrl` Click | Toggle a single cell in or out of the selection | | Click + drag | Drag-select a range | | `⌘ C` / `Ctrl C` | Copy selection as TSV | | `⌘ A` / `Ctrl A` | Select every cell in the table (after a first selection) | | `Esc` | Clear selection | The footer shows live stats (sum, average, count) for the current selection when amounts or numbers are selected. ## Discoverability Most shortcuts also appear: * as a tag next to the action inside the command palette * as a hint in the tooltip when hovering sidebar items If a shortcut is documented here but doesn't seem to fire, check that the focus isn't trapped inside a text input. Click outside the field first, then trigger the shortcut. # Monetize an AI product Source: https://docs.hyperline.co/guides/monetize-ai-products Use Hyperline to monetize AI products with usage-based billing, prepaid credits, wallets, subscriptions, and customer-facing balance workflows. AI products often combine predictable subscriptions with variable consumption. Customers may pay for seats, token usage, model calls, generated images, agent runs, data processing, or prepaid credit packs. Hyperline helps you turn those signals into billable products without building a separate billing system for AI usage. Use this page as an entry point when you are designing how to price, package, and bill AI consumption. ## Common AI monetization use cases | Use case | Example | Hyperline capabilities to use | | - | - | - | | Token or model usage | Charge based on tokens consumed by each model tier | [Usage events](/docs/usage/send-usage-data), [aggregators](/docs/usage/aggregators), and [usage-based products](/docs/products/overview#usage) | | Prepaid AI credits | Sell 10,000 credits that customers can spend across models, agents, or generations | [Credit products](/docs/credits/overview) with weighted aggregators | | Included allowance and overages | Include 1M tokens in a monthly plan, then bill additional usage | [Usage-based billing](/docs/usage/getting-started) and [subscriptions](/docs/subscriptions/manage) | | Enterprise budget control | Let customers prepay a balance, consume it over time, and top up when needed | [Credits](/docs/credits/overview), [wallets](/docs/wallets/balance), and [customer portal](/docs/customers/portal) | | AI add-ons | Add premium models, extra automation runs, or advanced features on top of a base subscription | [Products and prices](/docs/products/overview), subscriptions, and usage-based products | | Customer-facing consumption visibility | Show customers how usage or credit balances evolve over time | [Customer usage](/docs/usage/customer-usage), [credits](/docs/credits/overview), and [customer portal](/docs/customers/portal) | ## Choose a billing model ### Usage-based billing Usage-based billing works well when customers should pay for exactly what they consume during a billing period. Hyperline receives usage events, converts them into billable metrics with aggregators, and applies the price configured in your product catalog. Use it for token volume, API calls, workflow runs, image generations, storage, compute time, or any metric that should appear on the next invoice. Start with: * [Getting started with usage-based billing](/docs/usage/getting-started) * [Send usage data](/docs/usage/send-usage-data) * [Aggregators](/docs/usage/aggregators) * [Usage-based products](/docs/products/overview#usage) ### Prepaid credits Credits work well when customers should buy a package upfront and spend it flexibly across multiple AI actions. Several aggregators, each with its own weight, can consume one credit balance. For example, one lightweight model call can consume `1` credit, a premium model call can consume `5` credits, and an image generation can consume `10` credits from the same balance. This lets customers understand a single balance while your pricing still reflects different underlying costs. Start with: * [Credits overview](/docs/credits/overview) * [Credit products](/docs/products/overview#credit) * [Set up credit-based billing for an AI platform](/guides/credit-based-billing-ai) ### Subscriptions with allowances and overages Many AI products use a hybrid model: a recurring subscription gives access to the product and includes a usage allowance, while overages are billed separately. This is useful when customers want predictable pricing, but your costs still depend on consumption. Use this model when you want to package AI usage into tiers such as **Starter**, **Scale**, and **Enterprise**, while still charging for heavy usage beyond the included allowance. Start with: * [Configure usage-based billing](/guides/configure-usage-based-billing) * [Products and prices](/docs/products/overview) * [Manage subscriptions](/docs/subscriptions/manage) ### Wallets and customer balances Wallets are useful when you want to manage a monetary balance for a customer. Credits are usually better for productized AI consumption units. Wallets are better suited to prepaid cash balances, manual adjustments, or commercial credits that should offset future invoices. Start with: * [Wallet balance](/docs/wallets/balance) * [Customer portal](/docs/customers/portal) * [Coupons and credits](/docs/coupons/overview) ## Suggested setup path 1. Define the unit you want to monetize: tokens, requests, agent runs, documents processed, generated assets, or another AI-specific metric. 2. Send usage events to Hyperline, or use a data connector if your usage data already lives in another system. 3. Create aggregators that transform raw events into the billable metrics you want to price. 4. Choose the commercial model: usage-based billing, prepaid credits, subscription allowances, wallet balance, or a mix of those models. 5. Add the products to subscriptions, quotes, or self-serve flows so customers can buy and renew them. 6. Use customer usage, credit balances, invoices, and the customer portal to make consumption visible to your team and your customers. For most AI platforms, start with usage events and aggregators. They are the foundation for both usage-based billing and credit consumption. ## Related documentation Connect usage data and configure billable usage metrics. Sell prepaid credit packs and deduct usage from customer balances. Follow a complete example for credit-based billing on an AI platform. Let customers view balances, invoices, and payment information. # Retroactive subscription update Source: https://docs.hyperline.co/guides/retroactive-subscription-update Apply a Hyperline subscription change retroactively after the current period is already invoiced, using the advanced update flow with transition invoice. Sometimes you need to update a subscription after the current billing period has already been invoiced. For example, you forgot to apply a price increase at renewal, or your customer signed a contract amendment late. You may also have needed to add an extra product at the start of the period. This guide walks you through how to apply a subscription change retroactively using the [advanced update](/docs/subscriptions/update#advanced-update) flow, with either **At last renewal** or **At selected date**. It also explains how each transition invoice mode (**Issue transition invoice** vs **Issue separate credit note and invoice**) impacts the customer's invoices. ## When to use a retroactive update Use a retroactive update when: * The change should have taken effect earlier in the current billing period (or in a past period) * The invoice for the current period has already been issued and you want to correct it * You need a clean audit trail and version history of the change If the change can simply apply going forward, use **Next renewal** or **Immediately** instead. There's no need for a retroactive update. ## Choose when to apply the update In the advanced update flow, the **When to apply the update** step controls the effective date of the change: * **At last renewal**: Applies the update retroactively as of the start of the current billing period. This is the most common option when you want the change to look as if it had been configured from the beginning of the period. * **At selected date**: Applies the update at a specific date you set. Select a **date in the past** to make the change retroactive to that exact day (for example, mid-period when a contract amendment was signed). A subscription renewed on **March 1st** with a monthly plan at €100. On **March 20th** you realize a new add-on should have been included since March 1st. * Select **At last renewal** to apply the add-on as of March 1st. The full period is recalculated as if the add-on had always been there. * Select **At selected date**, then select **March 10th** if the add-on should only apply from that day onward. The period is split, and only the portion after March 10th includes the add-on. ## Choose the transition invoice mode Once you've selected the retroactive effective date and the new subscription configuration, the **Configure transition options** step lets you decide how to correct the already-issued invoice. Two modes are available for retroactive updates: ### Issue transition invoice Hyperline issues a single **transition invoice** on top of the existing invoice to settle the difference between what was originally billed and what should have been billed for the period. * The original invoice for the current period is **kept as-is** (not refunded) * A new invoice is generated for the **delta**: either a charge (if the customer owes more) or a credit note (if the customer was overcharged) * Best when you want a lightweight correction and to preserve the original invoice for accounting continuity Original invoice for March: **€100** (already paid). You apply a retroactive update **At last renewal** to add a €30/month add-on. With **Issue transition invoice**, Hyperline issues an additional invoice of **€30** for March. The customer keeps their original €100 invoice and receives a second €30 invoice covering the add-on for the same period. ### Issue separate credit note and invoice Hyperline **fully refunds** the original invoice for the current period (via a credit note) and issues a brand new invoice reflecting the updated subscription configuration. * The customer ends up with one credit note cancelling the original invoice, plus a new invoice for the corrected amount * Best when the original invoice is materially wrong and you want the final billing to look as if the new configuration had been in place from the start of the period * Only available for updates **At last renewal** Original invoice for March: **€100** (already paid). You apply a retroactive update **At last renewal** to swap the plan from €100/month to €150/month. With **Issue separate credit note and invoice**, Hyperline issues a **credit note of €100** cancelling the original invoice, and a new **€150 invoice** for March reflecting the new plan. The customer's net balance for the period is now €150 instead of €100. **Issue separate credit note and invoice** is only available when applying the update **At last renewal**. For updates **At selected date** in the past, use **Issue transition invoice** to settle the delta. **Spanish invoicing entities**: when the invoicing entity is registered in Spain (`ES`), Spanish invoicing rules do not allow a single netted transition invoice. **Issue transition invoice** is hidden. **Issue separate credit note and invoice** is the only mode available, on every effective date (**At last renewal**, **At selected date**, **Immediately**, and **Scheduled date**). The current period's invoice is always cancelled with a credit note, and a new invoice is issued for the updated configuration. ## Step-by-step instructions Navigate to the customer's subscription details page, click the **Actions** dropdown, then select **Update subscription**. Select **Advanced update** to access the full transition configuration. Select either: * **At last renewal** to apply the change retroactively from the start of the current billing period * **At selected date**, then select a date in the past for a mid-period retroactive change Select **Update current subscription** to edit the existing configuration, or **Update to a template or a plan** to reset the configuration from a template or plan. Make the changes that should have been in place as of the effective date (add a product, change a price, swap the plan...). Under **Transition invoice**, select how to correct the already-issued invoice: * **Issue transition invoice**: issues an additional invoice for the delta, keeping the original invoice intact * **Issue separate credit note and invoice**: refunds the original invoice and issues a new one reflecting the updated configuration (only with **At last renewal**) Use the invoice preview at this step to review both the transition invoice (or refund and new invoice) and the following invoice. This is the safest way to confirm the financial impact before applying the change. Review the update summary, then confirm. Hyperline updates the subscription retroactively and immediately generates the corresponding invoices (transition invoice, or credit note and new invoice). ## What happens after the update * The subscription configuration reflects the change as of the effective date * The corrective invoices (transition invoice or credit note + new invoice) are issued and follow your usual collection rules * The change is recorded in the [versions tab](/docs/subscriptions/update#subscription-versions), preserving a full audit trail of what changed and when Is something still unclear? Don't hesitate to reach out to our team via the in-app chat if you need additional support. # Subscription billing cycles Source: https://docs.hyperline.co/guides/subscription-billing-cycles Change the billing cycle alignment of a Hyperline subscription using the advanced update feature, with prorations, anchors, and timing examples. When a subscription is created, its start date or initial billing date determines its billing cycle. For example, a monthly subscription starting on March 10th renews on the 10th of each month. In some cases, you may need to realign the billing cycle. For instance, you might want all your subscriptions to renew on the 1st of the month. This guide walks you through how to change the billing cycle alignment of a subscription using the [advanced update (transition)](/docs/subscriptions/update#advanced-update) feature. ## Change the billing cycle alignment Use this when you want to shift a subscription's renewal date to a different day. For example, moving a monthly subscription that renews on the 10th to renew on the 1st instead. ### Step-by-step instructions Navigate to the customer's subscription details page, click the **Actions** dropdown, then select **Update subscription**. Select **Advanced update** to access the full transition configuration. Select **Scheduled date**, then select the date you want the new billing cycle to start on. This date should correspond to your desired new anchor date, either: * **A past date** matching the new anchor (e.g., the 1st of the current month if you want the subscription to renew on the 1st going forward) * **A future date** matching the new anchor (e.g., the 1st of the next month) If today is January 15th and the subscription currently renews on the 10th, you could select: * **January 1st** (past) to retroactively realign the billing cycle from the beginning of the current month * **February 1st** (future) to realign starting from the next month In the update source step, select **Update current subscription**. Since you only want to change the billing cycle alignment and not modify the products or pricing, keep the subscription configuration as-is. This step is key to realigning the billing cycle: 1. Under **Billing cycle alignment**, select **Start new period**. This resets the subscription billing dates to start a fresh cycle from the selected transition date, effectively making that date the new anchor for all future renewals. 2. Under **Transition invoice**, select the option that fits your use case: * **Issue transition invoice** to settle the period between the last renewal and the transition date * **Waive transition invoice** to skip billing for the partial period Use the invoice preview at this step to review both the transition invoice and the following invoice. This helps you verify that the new billing cycle alignment is correct before confirming. Review the update summary to verify that: * The transition date matches your desired new anchor date * **Start new period** is selected * The transition invoice setting is correct Confirm the update. The subscription now follows the new billing cycle, renewing on the selected anchor date going forward. ### What happens after the update Once the transition is applied: * The subscription's billing cycle resets to start from the transition date * All future renewals align to this new date (e.g., the 1st of each month) * If a transition invoice was generated, it covers the partial period between the previous renewal and the new anchor date * The subscription version history records this change in the [versions tab](/docs/subscriptions/update#subscription-versions) A monthly subscription renewing on the 10th is transitioned on February 1st with **Start new period** selected: * A transition invoice covers January 10th–January 31st (if not waived) * The new billing period runs from February 1st to February 28th * All future renewals happen on the 1st of each month Is something still unclear? Don't hesitate to reach out to our team via the in-app chat if you need additional support. # Upsell and downsell a subscription Source: https://docs.hyperline.co/guides/upsell-downsell-subscriptions Upsell or downsell a Hyperline subscription with the advanced update flow, or send a quote for subscription update that the customer signs. Upsells (adding products, increasing quantities, moving to a higher plan) and downsells (removing products, decreasing quantities, moving to a lower plan) are common changes on active subscriptions. Hyperline provides two ways to apply them, depending on whether the change needs customer approval: * **Advanced update**: apply the change directly from the subscription details page, with full control over the effective date and the transition invoice. * **Quote for subscription update**: send the customer a quote for signature; the change only takes effect once the quote is signed, or at the specified date after quote signature. This guide walks you through both flows. It then explains how two settings drive the pro-rata logic on the resulting invoices. The first is the effective date (**Next renewal**, **At last renewal**, **Immediately**, **Scheduled date**). The second is the transition invoice mode (**Waive**, **Issue transition invoice**, **Issue separate credit note and invoice**). ## Choose the right flow Best when you're applying the change on your side, with no customer signature required. Use it for internal amendments, corrections, or upsells and downsells agreed on outside of a quote. Best when the customer must approve the change. The upsell or downsell is captured in a signed document and only applies once the customer signs the quote. Both flows expose the same transition settings (effective date, billing cycle alignment, transition invoice mode), so the pro-rata logic described below applies identically to both. ## Upsell or downsell with the advanced update flow The **advanced update** flow gives you a multi-step process to configure exactly when and how the upsell or downsell is applied. From the customer's subscription details page, click **Actions** then **Update subscription**, and select **Advanced update**. Select the effective date of the change: * **Next renewal**: Applied when the current billing cycle ends. Recommended for upsells or downsells that should only impact future periods, with no pro-rata on the current one. * **Immediately**: Applied right now, mid-period. Recommended for a live upsell or downsell that must take effect today, with a pro-rated transition invoice for the remainder of the period. * **At last renewal**: Applied retroactively as of the start of the current period. Recommended when the change should have been in place from the start of the current period (see [Retroactive subscription update](/guides/retroactive-subscription-update)). * **Scheduled date**: Applied at a specific date in the future. Select **Update current subscription** to edit the existing configuration (add or remove products, adjust quantities, change prices). Alternatively, select **Update to a template or a plan** to move the customer to a pre-configured upsell or downsell plan. Under **Billing cycle alignment**, select whether to **Keep current period** or **Start new period** from the update date. Then, under **Transition invoice**, select how the current period should be settled: * **Waive transition invoice**: No transition invoice is issued. * **Issue transition invoice**: A transition invoice settles the current period based on the pro-rata logic described below. * **Issue separate credit note and invoice**: The current period's invoice is refunded and re-issued to reflect the new configuration (only available with **At last renewal**). Use the invoice preview at this step to review both the **transition invoice** and the **following invoice** before confirming. This is the safest way to validate the financial impact of the upsell or downsell. Review the update summary and confirm. Hyperline updates the subscription according to your effective date and generates the corresponding invoices. ## Upsell or downsell with a quote for subscription update Use a [quote for subscription update](/docs/quotes/subscription-update) when the customer needs to approve the upsell or downsell before it takes effect. The transition settings you configure on the quote (effective date and transition invoice mode) behave identically to the advanced update flow. The only difference is that Hyperline applies the change on quote signature (or on the scheduled date after signature) rather than immediately. From the subscription details page, click **Actions** then **Create update quote**. Alternatively, from the **Quotes** page, click **New quote** and select **Quote for subscription update**. Select one of: * **On quote signature**: The upsell or downsell is applied when the customer signs the quote. * **On selected date**: The upsell or downsell is applied on a future date, provided the customer signs the quote by then. Keep the current configuration and adjust it (add or remove products, edit quantities and prices, add or remove coupons or phases). You can also start from a template for pre-configured upsell and downsell scenarios. Click **Revise transition** to select the billing cycle alignment (**Keep current period** or **Start new period**) and the transition invoice mode (**Waive transition invoice** or **Issue transition invoice**). The pro-rata logic on the transition invoice is the same as with the advanced update flow. Finalize, review, and send the quote. Once signed, Hyperline applies the change automatically (either immediately or on the scheduled date) and generates the transition invoice according to your settings. While a quote for subscription update is pending signature, you cannot edit the source subscription directly. You can still create additional open quotes on the same subscription. This is useful when negotiating several upsell scenarios in parallel. ## Effective date and pro-rata logic on the transition invoice The effective date you select controls both **when** the new configuration starts and **what** the transition invoice looks like. Below is how each option impacts the transition invoice for a typical upsell or downsell. ### Next renewal * The current period runs to its scheduled end date, invoiced as originally configured. * The new configuration starts at the next renewal. The first invoice under the new pricing is the regular period invoice. * **No transition invoice is generated** (no pro-rata is needed). * Best for upsells and downsells that shouldn't disturb the current period. A customer is on a monthly plan at €100, renewing on the 1st of each month. On **March 15th**, you upsell them to a €150/month plan with **Next renewal** as the effective date. * March 1st–31st: invoiced €100 as originally scheduled. * April 1st: the new plan starts and the customer is invoiced €150 for April. * No transition invoice. ### Immediately * The new configuration takes effect on the update date, mid-period. * The transition invoice settles the current period on a **pro-rata basis**: * The **removed** or **downgraded** products are credited for the unused portion of the period (elapsed days are billed at the old price, remaining days are credited). * The **added** or **upgraded** products are charged for the remaining portion of the period. * Best for live upsells and downsells that should apply from today. Same customer on a €100/month plan renewing on March 1st. On **March 16th** (half of a 30-day period elapsed), you upsell them to a €150/month plan **Immediately** with **Issue transition invoice**. * The old plan is billed for the first 15 days: €100 × 15/30 = **€50**. * The new plan is billed for the remaining 15 days: €150 × 15/30 = **€75**. * The €100 already invoiced on March 1st is offset. The transition invoice charges **€25** (€75 for the new plan minus the €50 credit for the unused half of the old plan). * On April 1st, the customer is invoiced €150 for the full April period. If it were a downsell to a €60/month plan instead, the transition would produce a **credit** on the transition invoice. The unused portion of the old plan is worth more than the pro-rated new plan. ### At last renewal * The new configuration is applied retroactively, as if it had been in place from the start of the current period. * Two transition invoice modes are available: * **Issue transition invoice**: Hyperline keeps the original invoice for the current period as-is. It then issues a transition invoice for the **delta** between what was originally billed and what should have been billed for the full period under the new configuration. * **Issue separate credit note and invoice**: Hyperline fully refunds the original invoice for the current period via a credit note. It then issues a new invoice reflecting the new configuration for the full period. * Best when the upsell or downsell was agreed on retroactively and should cover the current period entirely. See [Retroactive subscription update](/guides/retroactive-subscription-update) for the full walkthrough. Customer on a €100/month plan, March invoice of €100 already issued and paid. On **March 20th**, you upsell them to €150/month **At last renewal**. * With **Issue transition invoice**: the €100 March invoice is kept, and a second invoice of **€50** is issued to cover the delta for March. * With **Issue separate credit note and invoice**: a **credit note of €100** cancels the original invoice, and a new **€150 invoice** is issued for March. **Spanish invoicing entities**: when the invoicing entity is registered in Spain (`ES`), only **Issue separate credit note and invoice** is available for the transition invoice. This applies to every effective date, not just **At last renewal**. Spanish invoicing rules do not allow a single netted transition invoice. Hyperline always cancels the current period's invoice with a credit note and issues a new invoice for the updated configuration. ### Scheduled date * The upsell or downsell is applied on a specific future date. * Between now and the scheduled date, the subscription continues under the current configuration and is invoiced normally. * On the scheduled date, the transition follows the same pro-rata logic as **Immediately** if the date falls mid-period, or as **Next renewal** if it aligns with a renewal. * Best for planned upsells (for example, a customer confirms today that they'll expand on the 1st of next quarter). Customer on a €100/month monthly plan renewing on the 1st. You schedule an upsell to €150/month on **April 15th**. * March and early April: invoiced normally on the €100 plan. * April 1st: invoiced €100 for the April period as usual. * April 15th: the upsell takes effect, and Hyperline generates a pro-rated transition invoice for the second half of April. It charges the delta between the new and old plan for the remaining days. * May 1st: invoiced €150 for the full May period. ## Billing cycle alignment Alongside the effective date, the **billing cycle alignment** on the transition options step controls whether the customer's renewal date changes after the upsell or downsell: * **Keep current period**: The renewal date stays the same. The transition invoice covers the remainder of the existing period (if applicable), and the next invoice lands on the original renewal date. * **Start new period**: A fresh billing cycle starts on the effective date. The customer's future renewal date shifts to align with the update. Customer renews monthly on the 1st. On **March 16th**, you apply an upsell **Immediately**. * With **Keep current period**: April 1st stays the next renewal date, and the customer is invoiced for the second half of March on the transition invoice. * With **Start new period**: a new monthly period starts on March 16th, and the next renewal is April 16th. ## Choosing the right combination | Scenario | Effective date | Transition invoice | | - | - | - | | Upsell that should apply from the next renewal | Next renewal | Not applicable | | Live upsell in the middle of the period | Immediately | Issue transition invoice | | Live downsell mid-period, refund unused portion | Immediately | Issue transition invoice | | Upsell agreed on last week, should cover the current period | At last renewal | Issue transition invoice | | Correction where the current period invoice was materially wrong | At last renewal | Issue separate credit note and invoice | | Upsell confirmed today, effective on a future date | Scheduled date | Issue transition invoice | | Cosmetic change (relabelling, custom properties) with no billing | Immediately | Waive transition invoice | Whenever you're unsure, use the invoice preview at the **Configure transition options** step (advanced update) or the **Revise transition** modal (quote for subscription update). Confirm that the transition invoice matches what you expect before confirming or sending the quote. ## What happens after the upsell or downsell * The subscription reflects the new configuration from the effective date. * Any transition invoice, credit note, or refund follows your usual payment collection rules. * Previous configurations are preserved on the **Versions** tab of the subscription details page, providing a full audit trail of the upsell or downsell. Is something still unclear? Don't hesitate to reach out to our team via the in-app chat if you need additional support. # Adyen Source: https://docs.hyperline.co/integrations/adyen Collect card and local payments through Adyen on Hyperline with one-click connection, payment orchestration, and automatic reconciliation. ## Prerequisites You need to have an [Adyen](https://www.adyen.com) account, finished Adyen's onboarding flow, and admin rights on Hyperline. ## Setup If [Adyen](https://www.adyen.com) is your preferred Payment Service Provider, connecting it with Hyperline is a straightforward process: 1. In the menu, select **Settings** 2. Select **Payment** 3. Click **Connect payment provider**, then Adyen This will redirect you to the Adyen login page where you will have to enter your account credentials and click **Continue**. Once the process is completed, you will see Adyen appearing as **Active** in the Payment page. You can connect multiple Adyen accounts to Hyperline so that payments are routed based on your invoicing entities and preferences. ## Payment methods Adyen through Hyperline supports: * **Card** payments from major card schemes such as Visa, Mastercard, American Express, Discover & Diners, JCB and more, depending on country and locality * **Direct Debit** payments including SEPA (EU), Bacs (UK), and ACH (US, in USD) ## Customer information Each time you bill a customer in Hyperline, the corresponding payment details (including payment methods and mandates) are automatically created and managed by Hyperline in your Adyen account. Additionally, Hyperline integrates payment method collection forms into our hosted pages (checkout, customer portal, invoice page, and quote page), requiring no technical effort on your part. This seamless integration ensures that customer data and payments remain synchronized between Hyperline and Adyen, streamlining transaction management and customer information handling. # Airwallex Source: https://docs.hyperline.co/integrations/airwallex Collect card and bank transfer payments through Airwallex on Hyperline, with automatic customer sync, payment routing, and reconciliation. ## Prerequisites You need to have an [Airwallex](https://www.airwallex.com) account, finished Airwallex's onboarding flow, and admin rights on Hyperline. ## Setup If [Airwallex](https://www.airwallex.com) is your preferred Payment Service Provider, connecting it with Hyperline is a straightforward process: 1. In the menu, select **Settings** 2. Select **Payment** 3. Click **Connect payment provider**, then Airwallex This will redirect you to the Airwallex login page where you will have to enter your account credentials and click **Continue**. Once the process is completed, you will see Airwallex appearing as **Active** in the Payment page. You can connect multiple Airwallex accounts to Hyperline so that payments are routed based on your invoicing entities and preferences. ## Payment methods Airwallex through Hyperline supports: * **Card** payments from major card schemes such as Visa, Mastercard, American Express, JCB, UnionPay, Discover and Diners Club, depending on country and locality * **Direct Debit** payments including SEPA (EU), Bacs (UK), or ACH (US) ## Customer information Each time you bill a customer in Hyperline, the corresponding customer profile and payment details (including payment methods and mandates) are automatically created and managed by Hyperline in your Airwallex account. Additionally, Hyperline integrates payment method collection forms into our hosted pages (checkout, customer portal, invoice page, and quote page), requiring no technical effort on your part. This seamless integration ensures that customer data and payments remain synchronized between Hyperline and Airwallex, streamlining transaction management and customer information handling. If you already have an Airwallex account with existing customers and payment methods, you have the possibility **to import them in Hyperline**. It is particularly useful when you configure your account. Please contact support if you are interested. # Anrok Source: https://docs.hyperline.co/integrations/anrok Use Anrok as the tax engine for Hyperline: automate sales tax calculation, product mapping, and compliance for US transactions and beyond. ## Prerequisites You need to have an [Anrok account](https://anrok.com). Hyperline connects only one tax engine at a time per invoicing entity. To use Anrok, configure all your products and jurisdictions in Anrok. ## Setup If [Anrok](https://www.anrok.com) is your preferred tax engine, you need to ask us for a connection, and we'll do the setup for you inside Hyperline. ### Get Anrok API key First, provide us with an Anrok API key from your Anrok account. 1. In the menu, select **Settings** 2. At the bottom, click **Manage API keys** 3. Click **Create API key** 4. Copy the API key. Once Hyperline has activated the feature for you, you'll be able to click **Connect** in the **Integrations** page. ### Configure Anrok accounting timezone Configure the timezone of your Anrok account in the **Settings** page. Otherwise, you'll get errors when you create an invoice. 1. In the menu, select **Settings**, and in the **Accounting** section, select **Timezone**. ### Configure Anrok as tax engine Click **Taxes** in the settings menu and select **Anrok** as tax engine. ### Configure products To map your Hyperline products to Anrok products, go to the **Products** page. 1. Click **Products** in the menu 2. Click **Add product** 3. Fill in the form with the following information: You'll enter the **Product ID** on the Hyperline product page. You can share it across multiple products in Hyperline afterwards. Here is an article from Anrok that explains the tax categories: [Anrok Tax Categories](https://help-center.anrok.com/hc/en-us/articles/4412669541907-Available-tax-categories-for-product-IDs) 4. Following Anrok's recommendation, create a default product. Hyperline uses it when a product has no saved mapping. Name it **default\_hyperline\_product\_anrok** and set the **Product ID** to **default\_hyperline\_product\_anrok** with the default tax categories that will be used. If you don't create it, Hyperline uses one of your mapped products as the default. 5. Click **Save** Finally, add the Anrok product ID to each product in Hyperline. Set it in the accounting section of each product on the **Products** page. ### How Hyperline picks the Anrok product For each line of an invoice or credit note, Hyperline sends Anrok a product ID, resolved in this order: 1. **The mapped product**: the Anrok product ID saved on the Hyperline product. 2. **The Hyperline product ID**: if the product isn't mapped but an Anrok product exists with the Hyperline product ID (e.g. `itm_xxx`) as its **Product ID**, Hyperline uses that Anrok product. 3. **The default product**: `default_hyperline_product_anrok`, if you created it. 4. **Any mapped product**: otherwise, one of your mapped products. Instead of mapping each product in Hyperline, you can create your Anrok products using the Hyperline product IDs as **Product ID**. Hyperline picks them up automatically within one hour of their creation in Anrok. # Attio Source: https://docs.hyperline.co/integrations/attio Connect Attio CRM with Hyperline to sync customers, subscriptions, and revenue data, and view billing details and customer intelligence on Attio records. The Hyperline-Attio integration connects your Attio workspace with Hyperline. With this integration, you can access dedicated widgets and actions directly from your Attio record pages to create and manage Hyperline quotes, subscriptions, and customers without leaving your CRM. These features embed the full Hyperline interface inside Attio. In addition, the integration enables optional and automatic data synchronization between Hyperline entities (such as quotes, subscriptions, and invoice details) and Attio's custom objects. You always have up-to-date information, and you can use this data for internal automations, workflows, and reporting within Attio. ## Prerequisites You must have a valid [Attio account](https://attio.com) with admin rights as well as access to the settings of your Hyperline account. Create a dedicated Attio test workspace before going live, and use the [test mode](../docs/getting-started/sandbox) of your Hyperline account during setup and experimentation. ## Embedded Hyperline UIs in Attio ### Installation Upon connecting your Attio account to Hyperline, Hyperline automatically installs the Hyperline app in your Attio workspace. Then configure a **Workspace Connection**: 1. In Attio, go to **Workspace settings** > **Apps** > **Hyperline** > **Workspace Connection** > **Connect**. 2. Enter an [API key created in your Hyperline settings](../api-reference/docs/authentication#generate-an-api-key) with **read access**. #### Sandbox To use the Hyperline Attio app with your Hyperline **sandbox (test mode)** account, go to **Workspace settings** > **Apps** > **Hyperline** > **Settings** in Attio, and select **Sandbox** as the environment. In this case, use an API key created in your Hyperline **sandbox** account for the Attio app Workspace Connection. ### Record actions Once the integration is set up, new Hyperline actions become available directly from your Attio company and deal records. You can: * Create Hyperline quotes. * Create Hyperline subscriptions. * Manage the related Hyperline customer. Each action opens a dedicated Hyperline interface embedded directly within Attio. You get the full Hyperline experience without leaving your CRM. ### Widgets In addition to record actions, the integration provides dedicated Hyperline widgets that you can embed directly into your Attio company and deal record pages. #### Billing widgets * **Subscription widget**: Displays a preview of the customer's active subscription along with its associated ARR. Clicking the widget opens the corresponding Hyperline subscription page. * **Quote widget**: Displays a preview of the currently open quote and its associated value. Clicking the widget opens the corresponding Hyperline quote page. If multiple subscriptions or quotes are linked to the Attio record, the widget instead displays the number of related items. Clicking it opens a list of all associated subscriptions or quotes. ##### Settings You can configure billing widgets and record actions from **Settings** > **Integrations** > **Attio**. ###### Allow creating new customer When enabled, you can create a Hyperline customer when you trigger a billing action from an Attio company or deal that is not yet linked to one, then continue with the action. When disabled, actions are blocked until a matching Hyperline customer exists and is linked to the Attio record. #### Customer intelligence widget Add the **Customer intelligence** widget to an Attio company or deal record page to review the linked Hyperline customer's latest monitoring result without leaving your CRM. When available, the widget displays: * The customer's health score out of 100. * A health badge: `Healthy`, `Needs attention`, `At risk`, or `Critical`. * A summary of the customer monitoring analysis. Click the widget to open the detailed monitoring result in an embedded Hyperline view. If no result is available, clicking it opens the Hyperline customer page instead. When no score is available, the widget shows the monitoring or analysis status, or **No monitoring run yet**. Monitoring requires the [Customer Intelligence paid add-on](../docs/customer-intelligence/overview) and a [customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent). The CRM record must be linked to a Hyperline customer using the [reconciliation rules below](#data-reconciliation), and your Hyperline role must allow you to view customers. If the widget shows **No linked customer**, use **Link customer** when available to associate the record with a Hyperline customer. ### User access You control how Attio users get access to Hyperline with the **Automatically register users** toggle in the **User access** section of **Settings** > **Integrations** > **Attio**. * **Enabled**: Attio users do not need an existing Hyperline account. When a user triggers a Hyperline action for the first time, Hyperline automatically creates a corresponding Hyperline user with their Attio email address. Hyperline assigns this user to your default Hyperline role (the ['Account manager' role](../docs/account/users-permissions#default-role) if not changed). * **Disabled**: Hyperline does not create users from Attio activity. Only Attio users who are already members of your Hyperline workspace can access Hyperline interfaces in Attio. [Invite users](../docs/account/users-permissions#invite-members) before they use the integration. If email matching domains are configured for your account, the **User access** section lists them. Hyperline matches an Attio user to an existing Hyperline user with the same email name (the part before the `@`) on any of these domains. For example, with `acme.com` and `acme.io` configured, `jane@acme.io` in Attio matches the existing Hyperline user `jane@acme.com`. These domains are read-only in the settings. Contact support to change them. When Hyperline interfaces open inside Attio, Hyperline applies the user's Hyperline role to ensure the correct view and edit permissions. You manage these permissions directly in Hyperline under **Settings** > **Team**. ### Data reconciliation When retrieving Hyperline customer data from an Attio company or deal record, Hyperline applies the following lookup mechanism: 1. If it's a deal record, Hyperline uses the associated company record for the lookup. 2. If the company record is already linked to a Hyperline customer through the **Integrations** section of the customer page, Hyperline uses that customer. 3. If the company record has a value in the Hyperline customer ID custom field, Hyperline looks for the corresponding customer. 4. If the company record has a value in the Hyperline external ID custom field, Hyperline looks for a customer whose ID or external ID matches that value, or whose linked Stripe customer ID matches that value (for example, a customer imported from Stripe). If the Attio company and the Hyperline customer were not previously linked, Hyperline automatically creates the link. This requires the integration settings to allow it: customer sync enabled, sync direction including Attio → Hyperline, and the company flagged for sync. If Hyperline finds a customer but the settings do not allow automatic linking, Hyperline surfaces the suggested customer in Attio, along with an action to manually trigger the link. If Hyperline finds no customer but the **Allow creating new customer** setting is enabled, the Attio user can create a new related Hyperline customer and proceed with the desired action. ## Data synchronization In addition to the fully built-in embedded UIs, the integration can also synchronize data from Hyperline to Attio custom objects. This synchronization is optional, and you can configure it afterward. When you connect your Attio workspace, you select which entities to synchronize in the Hyperline settings. Hyperline then automatically creates the required custom objects and their associated fields in Attio if they do not already exist. It also sets up the synchronization mechanisms. Deleting or manually modifying Hyperline custom objects and custom fields in Attio may break the integration and lead to unexpected behavior. Changing the data you select to synchronize requires reconfiguring the integration. This process may take a few minutes to complete. ### Customers sync When enabled, Hyperline customers are synchronized with Attio companies. You can select the synchronization direction (one-way or bidirectional). During the integration setup, Hyperline creates a **(Hyperline) Synchronize** checkbox custom field (`hyperline_sync` slug) on the Company object. Hyperline imports and synchronizes an Attio company only when this checkbox is enabled. Hyperline ignores companies without it checked. ### Customer custom properties Customer custom properties use different paths for inbound and outbound synchronization: * **From Attio company attributes to Hyperline**: Create an attribute on the Attio Company object whose slug exactly matches the Hyperline custom property `slug`. When you synchronize customers from Attio, Hyperline imports this value into the matching existing customer custom property. Changes in Hyperline do not update this Attio attribute. * **From Hyperline to custom property value records**: Enable **Custom property values** in the integration settings. Hyperline creates one record for each value in its dedicated custom property value object and links customer values to the related Attio company. This option also keeps each property's name, type, and value available as separate attributes. If a Hyperline customer custom property uses the `customer_tier` slug, create an Attio company attribute with the `customer_tier` slug. Set its value in Attio to import it into Hyperline when the customer syncs. The matching Attio company attribute must already exist, and the integration must be able to read it. Hyperline does not create it automatically. When you use the custom object option, Hyperline creates the required object and attributes during integration setup. ### Mapping Below are the object mappings between Hyperline entities and Attio custom objects. Object and field mappings between Hyperline entities and Attio custom objects ### Turn customer fields on or off You can select which default customer fields Hyperline syncs. To stop syncing specific fields, for example if you manage the currency or billing address only in Attio, configure the customer field mappings. 1. In the Attio integration settings, go to the customer synchronization section. 2. Click **Configure field mappings**. 3. In the **Customer field mappings** modal, use the toggle next to each field to turn its sync on or off. Each field shows its fixed Attio destination (company attribute) below its name. 4. Click **Save changes**. Changes apply in the sync direction you configured. Disabled fields keep their existing values. Click **Cancel** to close the modal without saving. You can't turn off fields that Hyperline needs to identify and link customers. Their toggles are locked. Creating new customers may still require some fields to be synced. ### Manually trigger a sync You can also manually trigger customer data synchronization from the Hyperline customer page. In the **Integrations** dropdown, click **Sync with Attio** to push (or pull, depending on the sync direction) the customer's data and send all associated quotes, subscriptions, and invoices to Attio. ## Troubleshooting If data is missing or synchronization fails, open **Settings** > **Integrations** > **Attio** > **View issues** in Hyperline for details. ### Common issues **Embedded Hyperline views don't load, or an action loads forever** This happens when your browser blocks third-party cookies, which Hyperline needs to authenticate the embedded view inside your CRM. Allow third-party cookies for `[*.]hyperline.co`, then reload the page: Browsers block links to settings pages, so the addresses below aren't clickable. Copy the address and paste it into a new browser tab. * **Chrome / Arc**: open `chrome://settings/cookies`, then under "Sites allowed to use third-party cookies" add `[*.]hyperline.co` (or select "Allow all cookies"). See [Google's guide](https://support.google.com/chrome/answer/95647). * **Edge**: open `edge://settings/content/cookies` and add `[*.]hyperline.co` under "Allow". See [Microsoft's guide](https://support.microsoft.com/microsoft-edge/temporarily-allow-cookies-and-site-data-in-microsoft-edge-597f04f2-c0ce-f08c-7c2b-541086362182). * **Safari**: open Settings > Privacy and uncheck "Prevent cross-site tracking". See [Apple's guide](https://support.apple.com/guide/safari/manage-cookies-sfri11471). * **Firefox**: click the shield icon in the address bar and turn off "Enhanced Tracking Protection" for this site, or add an exception under Settings > Privacy & Security. See [Mozilla's guide](https://support.mozilla.org/kb/enhanced-tracking-protection-firefox-desktop). Also disable any browser extension that blocks cookies or trackers for this site. ## Disconnect You can disconnect the integration at any time by clicking **Disconnect** in the top-right corner of the Attio integration settings page. Disconnecting the integration stops all synchronization. The custom objects, custom fields, and any previously pushed data in Attio remain intact. Hyperline does not delete them. # Claap Source: https://docs.hyperline.co/integrations/claap Connect Claap with Hyperline to attach meeting recordings, participants, and transcripts to customers and feed the customer monitoring agent. [Claap](https://www.claap.io) is a meeting recorder and video workspace that captures and transcribes customer calls. Connecting Claap lets Hyperline attach your recorded customer calls to the matching Hyperline customers. The customer monitoring agent can then combine what was said on a call with contract, subscription, invoice, payment, and usage data. Claap is part of [Customer intelligence](../docs/customer-intelligence/overview), a paid add-on. The Claap card only appears in **Settings > Integrations** when Customer intelligence is enabled for your account. Contact the Hyperline team through the in-app chat to enable it. ## Prerequisites * A valid [Claap account](https://www.claap.io) with recordings in your workspace. * A Claap API key, created from your Claap settings. * Admin rights on your Hyperline account. ## Connect Claap Before connecting, add your own company email domain (for example `yourcompany.com`) to **Settings > Customers > Excluded email domains**. CRMs often store your team members as contacts on customer records. Because your team joins every call, Hyperline can attach calls to the wrong customer based on their addresses unless you exclude the domain. Hyperline validates the key immediately and rejects it if it is invalid or revoked. The integration appears as connected and Hyperline starts matching Claap recordings to Hyperline customers. The connection is read-only. Hyperline never creates, edits, or deletes anything in Claap. ## What Hyperline fetches For every matched recording, Hyperline stores: | Data | Details | | - | - | | Recording | Claap recording identifier and title | | Timing | Start and end date and time, and duration | | Participants | Name and email of each participant, and whether they attended | | Transcript | The transcript of the recording, when Claap has produced one | Hyperline does not download the video or audio files. Only the details and transcript listed above are stored. ### Summaries Claap does not provide a written summary through its API. When a transcript is available, Hyperline generates the meeting summary itself from that transcript. ### Which recordings are matched Claap cannot filter recordings by participant, so Hyperline scans the workspace and matches locally. A recording is attached to a customer when at least one participant email corresponds to: * the customer **Domain**, meaning any participant using an email address on that domain * the customer **Billing email** * one of the customer **Invoice emails** * a contact email synced from a connected CRM Hyperline does not store recordings that it cannot match to a customer. Keep customer **Domain** and **Billing email** values up to date. They are the main signals used to attach a Claap recording to the right customer. ## Synchronization Hyperline synchronizes Claap in two ways: * **Daily workspace synchronization**: once a day, Hyperline scans recent recordings and attaches the new ones to the matching customers. * **On-demand customer synchronization**: Hyperline also refreshes data when the customer monitoring agent analyzes a customer, and when you click **Sync meetings** from the customer's Claap panel. Synchronization is incremental. Recordings already stored are not fetched again, and a transcript already downloaded is never downloaded twice. Each run processes a bounded number of recordings and transcripts, so a Claap workspace with a large history is backfilled progressively over successive runs rather than in a single pass. ## Where Claap data appears * **Customer page**: the **Integrations** section shows a Claap row with the most recent meeting. Open it to browse synced meetings with their participants, summary, and transcript, or to trigger **Sync meetings**. * **Monitoring agent**: enable Claap from the agent's **Connectors** tab. See [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent). * **Analysis results**: Claap appears under **Data sources** when call context was used. ## Manage the integration Open **Settings > Integrations** and select **Claap**. Synchronization errors, such as a revoked key, are reported on this page. Use **Disconnect** to stop synchronizing new recordings. Revoke the API key in Claap as well if you want to invalidate it entirely. ## Related * [Customer intelligence](../docs/customer-intelligence/overview) * [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent) * [Integrations overview](./overview) # DATEV Source: https://docs.hyperline.co/integrations/datev Connect Hyperline to DATEV Buchungsdatenservice to export debtor master data, invoices, credit notes, payments, and linked PDFs to your tax adviser. [DATEV](https://www.datev.de) is accounting and tax software used by German tax advisers (Steuerberater) and their clients. Hyperline connects through **DATEV Buchungsdatenservice** and sends debtor master data, outgoing invoices, credit notes and corrections, payment bookings, and the invoice PDFs linked to their bookings. This guide is written for both the Hyperline administrator and the tax adviser who receives the data. ## Prerequisites Buchungsdatenservice is a DATEV service that must be ordered and activated for the intended Beraternummer and Mandantennummer before any software can send data to it. Your DATEV administrator or tax adviser can do this at [go.datev.de/datenservices-einrichten](https://go.datev.de/datenservices-einrichten). The DATEV user who authorizes the connection must have access to that exact client dataset, and to both its Buchungsdatenservice and its document service. You need the fiscal-year start, account length, chart of accounts (SKR), debtor account range, the revenue / credit-note / payment accounts, and the tax codes. They fill in the settings below. You also need admin rights on Hyperline. Buchungsdatenservice is a DATEV product with its own activation and permissions. Hyperline cannot order it for you, and a dataset without it cannot be connected. ## Connect Hyperline redirects you to DATEV to authenticate. Hyperline never sees your DATEV password. Hyperline lists the datasets your DATEV user can reach, each with its company name, Beraternummer, and Mandantennummer. Search by any of the three, then select the one to connect. DATEV asks you to confirm long-term access for that dataset. Hyperline verifies it can reach that exact client before the connection is shown as active, and stores a long-lived credential so you do not reauthorize for every export. One Hyperline invoicing entity connects to exactly one DATEV client dataset, and DATEV issues one long-term credential per dataset. Connecting the same dataset again replaces the previous credential. After connecting, the integration page shows the connected dataset, the person who authorized it, the connection status, the date the access expires, and a link to DATEV's [connected applications](https://apps.datev.de/tokrevui) page. To switch to a different DATEV client later, reconnect the integration from the DATEV integration page and select another dataset. ## Settings Open the DATEV integration page in Hyperline to configure the connection. All of these settings are available under **Settings > Integrations > DATEV**. ### Client identification | Setting | Description | | - | - | | Consultant number | DATEV consultant number (Beraternummer) provided by your tax adviser. | | Client number | DATEV client number (Mandantennummer) inside your consultant's DATEV environment. | | Fiscal year start | First day of the fiscal year the export covers. Required by DATEV to validate booking dates. | The combination `consultantNumber-clientNumber` must match the DATEV client you authorized. If it does not, Hyperline displays a warning so you can update the settings or reconnect the matching client. ### Account settings | Setting | Description | | - | - | | SKR | Chart of accounts (Standardkontenrahmen) used by the client, typically `SKR03` or `SKR04`. | | Account length | Length of ledger account numbers, from 4 to 8 digits. Must match the DATEV client configuration. | | First debtor number / Collective debtor account | Starting number used when Hyperline creates new debtor (customer) accounts, or the collective debtor account used for manual exports. The minimum value is `10000`. | | Default invoice account code | Revenue account used for invoices, for example `8400` in `SKR03` or `4400` in `SKR04`. | | Default credit note account code | Revenue account used for credit notes. | | Default payment account code | Clearing account used for payments, for example `1200` in `SKR03` or `1800` in `SKR04`. | | Rounding account code | Optional account used to absorb rounding differences, for example `8736` or `4736`. | | Default tax code | Default VAT (Umsatzsteuer) code applied to bookings. | ### Document settings Invoice PDFs are filed in DATEV under three archive levels. Hyperline applies its own defaults when these are left empty. | Setting | Description | | - | - | | Category | Top archive level the documents are filed under. | | Folder | Second archive level, separating invoices from refunds. | | Register | Third archive level, by accounting month. | | Document type | Optional DATEV document type. Omitted from the upload when unset. | ### Export options | Setting | Description | | - | - | | Diktat code (Diktatkürzel) | Two- or three-letter code that identifies who created the export inside DATEV. | | Posting lock (Festschreibung) | When enabled, exported bookings are marked as final so they cannot be modified after import. | | Cost center 1 / Cost center 2 | Optional cost centers (Kostenstelle 1 / 2) attached to every booking. | Hyperline validates that the mandatory settings—consultant number, client number, fiscal year start, account length, and the three default account codes—are filled in. You cannot generate an export when any of these fields are missing. ## Synchronization rules Synchronization rules select revenue accounts for DATEV invoice and credit note bookings. Configure them with your tax adviser so each line uses an account from the correct chart of accounts. 1. Open **Settings > Integrations > DATEV**. In **Synchronisation rules**, open the rule count card or **No rules configured**, then click **Add rule**. 2. Select the **Invoicing entity** if prompted and enter a descriptive **Name**. 3. Under **Applied on**, filter by products, product type, coupons, currency, country, tax scheme, tax territory, tax rate class, billing interval, invoice types, or custom properties. 4. Under **Account configuration**, select a **Revenue account**. Use **Sync accounts from DATEV** to load the predefined accounts for your selected **SKR03** or **SKR04** chart, and add any additional account codes agreed with your tax adviser. 5. Click **Save changes** and review the account mappings before generating your next export. The account sync action supplies a predefined set of accounts. It does not fetch your tax adviser's full chart of accounts. Leave rule filters empty for a default revenue mapping, then add product-specific rules where needed. Your tax adviser uses **SKR03** and asks you to separate standard-rate and reduced-rate sales. Create rules using **Tax rate classes** with the revenue accounts agreed for each treatment, such as `8400` and `8300`. If no rule supplies a revenue account for a booking line, Hyperline exports a warning and leaves the account blank. Review and resolve missing-account warnings with your tax adviser before importing. Transaction and journal rules are not available for DATEV. Payment bookings use **Default payment account code**. Follow the [export workflow](#send-an-accounting-month-to-datev) to send the resulting bookings to DATEV. ## Send an accounting month to DATEV Navigate to **Settings > Integrations > DATEV** and scroll to the **DATEV exports** section. The range is interpreted in UTC. Sending is available only for a full calendar month; a partial range can still be downloaded as a file. Hyperline collects the invoices, credit notes, and payments for that month, uploads the invoice PDFs, then submits the booking file. How the transfer works: * Hyperline generates standard **DATEV-Format** files, not a proprietary format. * Movements are grouped by accounting month and transaction type; debtor master data is sent separately. * Invoice PDFs are uploaded **before** the booking file that references them. The document's stable identifier is written into the `Beleglink` field, so the supporting document opens directly from the booking in DATEV Rechnungswesen. * DATEV answers an upload with `202 Accepted`, which only means the import was queued. Hyperline polls the job until DATEV reports the import finished, and shows an error if it did not. Movement data that DATEV has already accepted is never submitted a second time automatically. If an accepted import later fails, you have to request a retransmission from Hyperline support, who create it as an audited copy of the original export. ## Manual ZIP exports The file-based flow remains available alongside the direct transfer, for any period and for sharing with a tax adviser who imports the files themselves. Select the period the export should cover, in UTC. Presets are available for the previous month, the current month, and the current year. Click **Generate DATEV export**. Hyperline builds a ZIP archive containing the DATEV-Format files. Open the generated export from **Reports > Exports**, download the ZIP, and import it into DATEV Rechnungswesen or share it with your tax adviser. Invoices and credit notes are selected by their issue date, and settled payments by their processing date. Both are compared against the selected range in UTC, so select your period accordingly if you work in another timezone. Generated exports remain available under **Reports > Exports** so you can download them again or share them with your accountant later. ## What is and isn't exported **In scope** * Outgoing invoices * Credit notes and invoice corrections * Payment bookings * Corporate debtor master data * Invoice PDFs linked to their bookings * German VAT and reduced VAT, configured tax-exempt and reverse-charge cases, third-country mappings * Foreign-currency invoice fields **Not in scope** * OSS (One Stop Shop) fields * Down-payment and final-invoice fields * Service-period / PRAP fields * Generalumkehr (general reversal) * Domestic §13b reverse charge * Payment cash discounts (Skonto) * Foreign-currency payment settlements * Natural-person debtor master data You must correct or exclude data that falls outside the supported scope before export. Hyperline refuses it rather than silently changing its tax treatment. ## Errors Hyperline shows an actionable error on the integration page for each of these, rather than failing silently: | What happened | What to do | | - | - | | Invalid Beraternummer or Mandantennummer | Check the numbers with your tax adviser and reconnect. | | Dataset without Buchungsdatenservice | Order and activate the service for that dataset at DATEV, then reconnect. | | Missing permission on the dataset | Have the DATEV administrator grant the authorizing user access to the client and its services. | | Authorization expired or revoked | Reconnect the integration from the Hyperline integration page. | | Invoice PDF invalid or too large | Regenerate the PDF (DATEV accepts PDFs up to 20 MB), then retry the export. | | DATEV rejected the export file | Review the export warnings and the affected invoice data with your tax adviser, then retry. | | DATEV is rate-limiting requests | Nothing. Hyperline retries automatically. | ## Support Contact Hyperline support first for anything involving the DATEV integration. Include the connected client dataset, the date and time of the export, the affected invoice or customer IDs, and the error shown in Hyperline. Hyperline keeps a technical log of every request exchanged with the DATEV gateway and investigates it before escalating anything to DATEV. ## Manage the integration You can disconnect DATEV from the Hyperline integration page at any time. Hyperline revokes the credential at DATEV and deletes the local connection. DATEV users can also review and revoke Hyperline's access at [apps.datev.de/tokrevui](https://apps.datev.de/tokrevui). To reauthorize, reconfigure, or resync this integration, see [Manage connected integrations](./manage-integration). # Exact Online Source: https://docs.hyperline.co/integrations/exact-online Push invoices, credit notes, and customers from Hyperline into Exact Online accounting for Belgian, French, German, and Dutch bookkeeping. [Exact](https://www.exact.com) is a Dutch technology company that provides software for small and medium enterprises. Exact Online is its cloud-based accounting software. ## Prerequisites You need to have a valid [Exact Online account](https://www.exact.com/fr/software/exact-online) and admin rights on Hyperline. ## Setup If your Exact Online user has access to several companies (divisions), log into Exact Online and switch to the division you want to connect to Hyperline. Do this **before** starting the connection flow. This also applies when reauthorizing or reconnecting an existing integration. Hyperline connects to whichever division is active in Exact Online at the moment of the OAuth flow. Select the Exact Online region that matches your account: **Belgium**, **France**, **Germany**, or **Netherlands**. Hyperline redirects you to the corresponding Exact Online login page. If you are not already logged into Exact Online, enter your credentials to proceed. Hyperline detects and configures your division automatically when Exact Online redirects you back. Configure the required codes and select your invoice push mode. See the [Invoice push mode](#invoice-push-mode) and [Settings](#settings) sections below for details. Your Hyperline account is ready to send invoices and credit notes. ## Connect multiple Exact Online accounts You can connect more than one Exact Online account to the same Hyperline workspace. This is useful if you operate several legal entities across regions (for example, one Belgian and one German subsidiary) and need to route each to its own Exact Online environment. To add another account, go to **Settings > Integrations**, click **Connect** on the Exact Online card again, and select the region for the new account. Each connection is tied to its own region and can be reauthorized independently from its provider page in Hyperline. ## Reconcile Hyperline and Exact Online customers If you already have existing customers in Exact Online, we'll need to link them with the corresponding customers in Hyperline. Our support team is available to assist you with this process during onboarding. ## Synchronization When you connect your Exact Online account, Hyperline **automatically sends invoices** with their complete details (including line items and PDF file). By default, only invoices and customers created after the connection date will sync. If you need to push older data to Exact Online, please contact our support team. ### Invoice PDF synchronization Invoice PDFs are automatically attached to invoices in Exact Online when they are first synced. If you need to re-attach or update PDFs for existing invoices (for example, if the initial attachment failed), please contact our support team. ### Customer synchronization Hyperline supports two modes of synchronization for customers: * **no synchronization**: customers are not synchronized with Exact Online. * **from Hyperline to Exact Online**: customers created in Hyperline are automatically created in Exact Online with their details. ### Payment synchronization Hyperline supports three modes of synchronization for payments: * **no synchronization**: payments are not synchronized with Exact Online. * **from Exact Online to Hyperline**: payments created in Exact Online are automatically created in Hyperline, and the status of the related invoice is updated accordingly. * **from Hyperline to Exact Online**: payments created in Hyperline are automatically created in Exact Online as bank journal entries. The synchronization delay is 1 hour maximum. ## Synchronization rules Synchronization rules select accounts and journals when Hyperline sends invoices, credit notes, or payments to Exact Online. | Entity type | Account mapping | Journal mapping | Available filters | | - | - | - | - | | **Invoice** | Revenue account for invoice and credit note lines, in both **Sales Invoices** and **Sales Entries** modes. | Sales journal when using **Sales Entries** mode. | Products, product type, coupons, currency, country, tax scheme, tax territory, tax rate class, billing interval, invoice types, and custom properties. | | **Transaction** | Asset account for payments sent from Hyperline to Exact Online. | Bank journal for the payment entry. | Payment providers, payment methods, bank accounts, and currencies. | 1. Open **Settings > Integrations > Exact Online**. In **Synchronisation rules**, open the rule count card or **No rules configured**, then click **Add rule**. 2. Select the **Invoicing entity** if prompted, enter a **Name**, and select **Invoice** or **Transaction** as the **Entity type**. 3. Under **Applied on**, add the filters that determine when the rule applies. 4. Select a **Revenue account** for invoice rules or an **Asset account** for transaction rules. You can also select a **Journal**, or create a rule that supplies only a journal. 5. Use **Sync accounts from Exact Online** or **Sync journals from Exact Online** if the required account or journal is missing, then click **Save changes**. A matching invoice rule's account takes precedence over the product account code, then the default invoice or credit note account code. Transaction rules take precedence over the default payment account and bank journal. Leave filters empty for a default rule and avoid overlapping rules with conflicting mappings. An explicitly configured **Credit note sales journal code** takes precedence over an invoice rule's journal for credit notes. Rules do not remove the product-code requirement in **Sales Invoices** mode or change the payment synchronization direction. Create a **Transaction** rule filtered to card payments and select a card clearing account and bank journal. Create another rule for bank transfers with the account and journal used for your bank receipts. ## Manage the integration To reauthorize, reconfigure, resync, or disconnect this integration, see [Manage connected integrations](./manage-integration). ## Invoice push mode Hyperline can push invoices to Exact Online in two different ways: * **Sales Invoices** (default): Invoices are created as sales invoices in Exact Online. This mode is useful if you need to manage invoices directly in Exact Online's invoice module. * **Sales Entries**: Invoices are created as sales entries (journal entries) in Exact Online. Enable the **Create sales journal entry instead of sales invoice** flag in your integration settings to use this mode. The push mode applies to both invoices and credit notes. ## Settings You can configure the following codes on the **Settings > Integrations > Exact Online** page: * **Invoice account code**: General Ledger (GL) account code used for invoices. * **Credit note account code**: GL account code used for credit notes. * **Payment account code**: GL account code used for payments created in Exact Online. * **Invoice sales journal code**: Sales journal used when pushing invoices as sales entries. By default, invoices will be created with the sales journal code *70*. * **Credit note sales journal code**: Sales journal used when pushing credit notes as sales entries. By default, credit notes will be created with the sales journal code *70*. * **Bank journal code**: Bank journal used when creating payments in Exact Online. * **Tax code**: Default tax code used when no tax code is matched for the line items' products. ### Product, tax and account codes Exact Online requires a **product code** for every invoice line item only when using the **Sales Invoices** mode. When using the **Sales Entries** mode, product codes are not required. You can configure tax codes in two different ways: * **At the product level**: Define a specific tax code for each product in Hyperline. This tax code will be used when the product is invoiced. * **At the invoicing entity level**: Configure tax codes with automatic computation of tax rates in the tax settings of the relevant invoicing entity. When configured this way, tax codes are automatically resolved according to what is configured in Hyperline and pushed to Exact Online. You can also define a General Ledger **account code** for every product. When no synchronization rule supplies an account, Hyperline uses the product account code, then the default invoice or credit note account code. # Front Source: https://docs.hyperline.co/integrations/front Connect Front with Hyperline to attach shared inbox conversations, tags, statuses, and messages to customers for the monitoring agent. [Front](https://front.com) is a shared inbox and customer communication platform for teams handling email and other channels together. Connecting Front lets Hyperline attach customer conversations to the matching Hyperline customers. The customer monitoring agent can then weigh open conversations and support pressure alongside contract, invoice, payment, and usage data. Front is part of [Customer intelligence](../docs/customer-intelligence/overview), a paid add-on. The Front card only appears in **Settings > Integrations** when Customer intelligence is enabled for your account. Contact the Hyperline team through the in-app chat to enable it. ## Prerequisites * A valid [Front account](https://front.com). * A Front API token, created from your Front settings. * Admin rights on your Hyperline account. ## Connect Front Hyperline validates the token immediately and rejects it if it is invalid or revoked. The integration appears as connected and Hyperline starts matching Front conversations to Hyperline customers. The connection is read-only. Hyperline never sends, replies to, or modifies anything in Front. ## What Hyperline fetches For every matched conversation, Hyperline stores: | Data | Details | | - | - | | Conversation | Front conversation identifier and subject | | Status | Normalized to `open`, `closed`, or `snoozed` | | Tags | The conversation tags, used as labels | | Contact | Handle and name of the conversation recipient | | Dates | Creation date and last update date | | Messages | Each message with its text, author, direction, and date | Front has no native conversation priority, so every synced conversation carries the same default priority in Hyperline. ### Which conversations are matched Hyperline resolves conversations per customer, in this order: 1. If the customer is linked to a Front **account**, Hyperline lists the conversations of that account's contacts. 2. Otherwise, Hyperline searches conversations mentioning the customer **Domain**, then keeps only those whose recipient uses an email address on that domain. Hyperline skips public email domains, such as `gmail.com`: a domain search on them would match unrelated conversations. The domain search is best-effort: Front's search has no wildcard on sender or contact, so Hyperline filters the results itself. Linking the Front account on the customer page gives more precise matching. ## Synchronization Hyperline synchronizes Front once a day, and also refreshes a customer on demand when the customer monitoring agent analyzes it. ## Where Front data appears * **Customer page**: the **Integrations** section shows a Front row with the most recent thread. Open it to browse synced conversations with their statuses, labels, and messages. * **Monitoring agent**: enable Front from the agent's **Connectors** tab. See [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent). * **Analysis results**: Front appears under **Data sources** when support context was used. ## Manage the integration Open **Settings > Integrations** and select **Front**. Synchronization errors, such as a revoked token, are reported on this page. Use **Disconnect** to stop synchronizing new conversations. Revoke the API token in Front as well if you want to invalidate it entirely. ## Related * [Customer intelligence](../docs/customer-intelligence/overview) * [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent) * [Integrations overview](./overview) # Gmail Source: https://docs.hyperline.co/integrations/gmail Connect Gmail per user to bring recent customer email threads into Hyperline, so the customer monitoring agent can weigh relationship signals. [Gmail](https://mail.google.com) is Google's email service. Connecting it lets Hyperline read the email threads you exchanged with your customers. The customer monitoring agent can then weigh how a relationship is going alongside contract, invoice, payment, and usage data. Gmail is part of [Customer intelligence](../docs/customer-intelligence/overview), a paid add-on. Contact the Hyperline team through the in-app chat to enable it. Gmail is **user-scoped**: each teammate connects their own mailbox from **Profile > Integrations**, not from the workspace-level **Settings > Integrations** page. Hyperline only sees the mailboxes of the users who connected. ## Prerequisites A Google account with the mailbox you want Hyperline to read. ## Connect Gmail You are redirected back to Hyperline and the connection appears as active for your user. Gmail and [Google Meet](./google-meet) are two separate connections that share nothing. You can share your calendar and meetings without sharing your mailbox, and the other way round. ### Requested permissions Hyperline requests read-only access to Gmail, plus your basic profile information to identify the connected account. The connection never sends, replies to, deletes, or modifies anything in your mailbox. ## What Hyperline fetches Hyperline never reads your whole mailbox. It searches Gmail once per customer domain, for messages sent to or received from that domain, and keeps only the results that match a known customer. For every matched email, Hyperline stores: | Data | Details | | - | - | | Thread | The Gmail thread identifier, so messages stay grouped by conversation | | Subject | The subject line | | Participants | Sender name and address, recipients, and copied addresses | | Body | The message content | | Date | When the message was received | Hyperline discards emails that do not match a customer domain and never stores them. Keep customer **Domain** values up to date. The domain is what decides which searches run and which messages are kept. ## Synchronization Hyperline synchronizes mailboxes once a day, for every user who connected their Google account. The recurring run looks one day back, so it only picks up new messages. A full-history search runs instead when the sync is scoped to a single domain, for example when a customer is created. That search is capped per domain, so a very large history is not retrieved in full. ## Where Gmail data appears * **Customer page**: the **Integrations** section shows a Gmail row with the most recent email. Open it to browse synced threads and their content. * **Monitoring agent**: email is handled separately from the other connectors. When Gmail is connected for users in your workspace, the agent can use recent customer email threads without a toggle in the agent's **Connectors** tab. * **Analysis results**: Gmail appears under **Data sources** when email context was used. ## Manage the connection Open **Profile > Integrations** to review or remove your own connection. Disconnecting stops Hyperline from reading your mailbox. Each teammate manages their own connection, so removing yours does not affect anyone else's. ## Related * [Google Meet](./google-meet) * [Customer intelligence](../docs/customer-intelligence/overview) * [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent) * [Integrations overview](./overview) # GoCardless Source: https://docs.hyperline.co/integrations/gocardless Collect SEPA, BACS, and ACH direct debit payments through GoCardless on Hyperline with one-click setup, mandate management, and reconciliation. ## Prerequisites You need to have a [GoCardless](https://gocardless.com) account, finished GoCardless's onboarding flow, and admin rights on Hyperline. ## Setup If [GoCardless](https://gocardless.com) is your preferred Payment Service Provider, integrating it with Hyperline is a straightforward process: 1. In the menu, select **Settings** 2. Select **Payment** 3. Click **Connect payment provider**, then GoCardless This will direct you to the GoCardless login page, where you will need to enter your account credentials and click **Connect Account**. Once the process is completed, you will see GoCardless appearing as **Active** in the Payment page. You can connect multiple GoCardless accounts to Hyperline so that payments are routed based on your invoicing entities and preferences. ## Payment methods GoCardless through Hyperline supports: * **Direct Debit** payments including SEPA (EU), Bacs (UK), or ACH (US) ## Customer information Each time you bill a customer in Hyperline, the corresponding customer profile and payment details (including payment methods and mandates) are automatically created and managed by Hyperline in your GoCardless account. Additionally, Hyperline integrates payment method collection forms into our hosted pages (checkout, customer portal, invoice page, and quote page), requiring no technical effort on your part. This seamless integration ensures that customer data and payments remain synchronized between Hyperline and GoCardless, streamlining transaction management and customer information handling. If you already have a GoCardless account with existing customers and payment methods, you have the possibility **to import them in Hyperline**. It is particularly useful when you configure your account. Please contact support if you are interested. ## Refund conditions Refunding payments via GoCardless is a user-friendly process, applicable for full or partial amounts through the dashboard or API. A concise timeline outlines the steps, with refunds typically processed 7 days after the payment charge date, unless you choose to opt out. Customers receive timely notifications, and funds usually arrive within one to two business days. The default 7-day refund delay is important for refund safety. Payments via the bank debit network may not settle immediately, posing a risk of late failure payments. We strongly advise you not to refund within 7 days to ensure sufficient settling time and minimize the potential for refunding unreceived funds. If you need more flexibility, you can opt out of this default restriction, as explained in the [official documentation](https://hub.gocardless.com/s/article/Refunding-payments?language=en_GB), providing a balance between user control and risk management. # Gong Source: https://docs.hyperline.co/integrations/gong Connect Gong with Hyperline to sync call recordings, participants, summaries, and transcripts into customer intelligence analyses and reports. [Gong](https://www.gong.io) is a revenue intelligence platform that records, transcribes, and analyzes customer calls. Connecting Gong lets Hyperline attach your recorded customer calls to the matching Hyperline customers. The customer monitoring agent can then combine what was said on a call with contract, subscription, invoice, payment, and usage data. Gong is part of [Customer intelligence](../docs/customer-intelligence/overview), a paid add-on. The Gong card only appears in **Settings > Integrations** when Customer intelligence is enabled for your account. Contact the Hyperline team through the in-app chat to enable it. ## Prerequisites * A valid [Gong account](https://www.gong.io) with call recording enabled. * A Gong user allowed to authorize applications for your Gong workspace. In most Gong accounts this is a technical administrator. * Admin rights on your Hyperline account. ## Connect Gong Before connecting, add your own company email domain (for example `yourcompany.com`) to **Settings > Customers > Excluded email domains**. CRMs often store your team members as contacts on customer records. Because your team joins every call, Hyperline can attach calls to the wrong customer based on their addresses unless you exclude the domain. If you are not already logged into Gong, enter your Gong credentials to proceed. Gong displays the read-only permissions Hyperline requests. Confirm to continue. You are redirected back to Hyperline and the integration appears as connected. Hyperline detects your Gong workspace automatically, so there is nothing else to configure. ### Requested permissions Hyperline requests read-only access to two areas of your Gong workspace: | Permission | Why it is needed | | - | - | | Read calls | Retrieve call metadata, participants, and the call brief, key points, and outcome produced by Gong | | Read transcripts | Retrieve the transcript of a call so the agent can reason on what was actually said | The connection is read-only. Hyperline never creates, edits, or deletes anything in Gong. ## What Hyperline fetches For every Gong call that involves one of your customers, Hyperline stores: | Data | Details | | - | - | | Call metadata | Gong call identifier, title, start date and time, and duration | | Participants | Name and email address of each participant, internal and external | | Summary | The call brief, key points, and call outcome produced by Gong | | Transcript | The transcript of the call, attributed to each speaker | Hyperline does not download audio or video recordings. Only the call details, summary, and transcript listed above are stored. ### Which calls are considered Only calls with at least one **external** participant are considered. Hyperline ignores internal-only calls, such as team meetings between colleagues. Among external calls, Hyperline keeps the ones that can be matched to an existing Hyperline customer. A call is matched when at least one participant email corresponds to: * the customer **Domain**, meaning any participant using an email address on that domain * the customer **Billing email** * one of the customer **Invoice emails** * a contact email synced from a connected CRM Hyperline does not store calls that it cannot match to a customer. Keep customer **Domain** and **Billing email** values up to date. They are the main signals used to attach a Gong call to the right customer. ### Summaries When Gong provides a brief, key points, or an outcome for a call, Hyperline uses it as the meeting summary. When a transcript is available but Gong has not produced a summary, Hyperline generates one from the transcript. ## Synchronization Hyperline synchronizes Gong in two ways: * **Daily workspace synchronization**: once a day, Hyperline reviews recent Gong calls and attaches the new ones to the matching customers. * **On-demand customer synchronization**: Hyperline also refreshes data when the customer monitoring agent analyzes a customer, and when you click **Sync meetings** from the customer's Gong panel. Synchronization is incremental. Calls already stored are not fetched again, and a transcript already downloaded is never downloaded twice. Each run processes a bounded number of calls and transcripts, so a Gong workspace with a large history is backfilled progressively over successive runs rather than in a single pass. A customer refresh keeps the most recent matched calls and retrieves transcripts for the most recent ones among them. ## Where Gong data appears * **Customer page**: the **Integrations** section shows a Gong row with the most recent meeting. Open it to browse synced meetings with their participants, summary, and transcript, or to trigger **Sync meetings**. * **Monitoring agent**: enable Gong from the agent's **Connectors** tab to let it use call context. See [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent). * **Analysis results**: Gong appears under **Data sources** when call context was used for an analysis. ## Manage the integration Open **Settings > Integrations** and select **Gong** to review the connection status. Synchronization errors, such as an expired authorization, are reported on this page. To stop using the integration, use **Disconnect**. Hyperline stops synchronizing new calls. Disconnecting in Hyperline does not remove the Hyperline application from your Gong workspace. To also revoke access on the Gong side, remove the application from your Gong settings. ## Related * [Customer intelligence](../docs/customer-intelligence/overview) * [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent) * [Integrations overview](./overview) # Google Meet Source: https://docs.hyperline.co/integrations/google-meet Connect Google Meet and Gemini notes with Hyperline to bring calendar meetings, participants, and transcripts into customer intelligence analyses. [Google Meet](https://meet.google.com) is Google's video conferencing service. When meeting transcription or the Gemini **Take notes for me** feature is enabled, each call can produce a transcript or a notes document. Connecting Google Meet lets Hyperline attach your customer meetings to the matching Hyperline customers. The customer monitoring agent can then combine what was said on a call with contract, subscription, invoice, payment, and usage data. Google Meet is part of [Customer intelligence](../docs/customer-intelligence/overview), a paid add-on. Contact the Hyperline team through the in-app chat to enable it. Google Meet is **user-scoped**: each teammate connects their own Google account from **Profile > Integrations**, not from the workspace-level **Settings > Integrations** page. Hyperline only sees the meetings of the users who connected. ## Prerequisites * A Google account with access to the calendar and meetings you want Hyperline to read. * Transcription or Gemini notes enabled on the meetings you want transcripts for. Without either, Hyperline can still record that the meeting happened, but has no content to analyze. ## Connect Google Meet Before connecting, add your own company email domain (for example `yourcompany.com`) to **Settings > Customers > Excluded email domains**. CRMs often store your team members as contacts on customer records. Because your team joins every call, Hyperline can attach calls to the wrong customer based on their addresses unless you exclude the domain. You are redirected back to Hyperline and the connection appears as active for your user. Google Meet and [Gmail](./gmail) are two separate connections that share nothing. You can share your calendar and meetings without sharing your mailbox, and the other way round. ### Requested permissions | Permission | Why it is needed | | - | - | | Calendar, read-only | List your meetings, their timing, and their attendees | | Meet, read-only | Retrieve the transcript produced by Google Meet | | Google Docs, read-only | Read the document produced by Gemini **Take notes for me** | Hyperline does not request access to Google Drive and cannot browse your files. The notes document is reached only through the calendar event or the meeting itself. The connection is read-only. Hyperline never creates or modifies calendar events, meetings, or documents. ## What Hyperline fetches | Data | Details | | - | - | | Calendar events | Title, start and end time, and attendees, over a window covering the last and next 90 days | | Meeting content | For a past meeting with a Meet link, the Gemini notes document when one exists, otherwise the Google Meet transcript | Recordings themselves are never downloaded. When Gemini notes exist, Hyperline prefers them: they contain both a written summary and the verbatim transcription, and they do not expire. Hyperline generates the meeting summary from whichever content it retrieved. Google deletes Meet transcripts 30 days after the call. A meeting older than that cannot be backfilled unless a Gemini notes document was produced, so connect before the calls you care about, not after. ### Which meetings are matched Meetings are attached to a customer when an attendee uses an email address on the customer **Domain**. Hyperline does not store meetings that it cannot match to a customer as customer meetings. Keep customer **Domain** values up to date. The attendee domain is the signal used to attach a meeting to the right customer. ## Synchronization Hyperline synchronizes calendars and meeting content once a day, for every user who connected their Google account. Meetings already stored are not fetched again. ## Where Google Meet data appears * **Customer page**: synced meetings appear with their participants, summary, and transcript. Calendar meetings without a recording are listed alongside recorded ones. * **Monitoring agent**: Google Meet has no toggle in the agent's **Connectors** tab, because it is connected per user rather than for the workspace. Its meetings reach the agent as soon as a teammate has connected their Google account. See [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent). * **Analysis results**: Google Meet appears under **Data sources** when call context was used. ## Manage the connection Open **Profile > Integrations** to review or remove your own connection. Disconnecting stops Hyperline from reading your calendar and meetings. Each teammate manages their own connection, so removing yours does not affect anyone else's. ## Related * [Gmail](./gmail) * [Customer intelligence](../docs/customer-intelligence/overview) * [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent) * [Integrations overview](./overview) # Grain Source: https://docs.hyperline.co/integrations/grain Connect Grain with Hyperline to attach meeting recordings, participants, summaries, and transcripts to customers for the monitoring agent. [Grain](https://www.grain.com) is a meeting recorder that captures, transcribes, and summarizes customer calls. Connecting Grain lets Hyperline attach your recorded customer calls to the matching Hyperline customers. The customer monitoring agent can then combine what was said on a call with contract, subscription, invoice, payment, and usage data. Grain is part of [Customer intelligence](../docs/customer-intelligence/overview), a paid add-on. The Grain card only appears in **Settings > Integrations** when Customer intelligence is enabled for your account. Contact the Hyperline team through the in-app chat to enable it. ## Prerequisites * A valid [Grain account](https://www.grain.com) with recordings in your workspace. * A Grain **workspace access token**, created from your Grain settings. * Admin rights on your Hyperline account. The token must be a workspace token rather than a personal one. Hyperline attributes recordings to customers across the whole workspace, so a token scoped to a single user would only ever surface that user's calls. ## Connect Grain Before connecting, add your own company email domain (for example `yourcompany.com`) to **Settings > Customers > Excluded email domains**. CRMs often store your team members as contacts on customer records. Because your team joins every call, Hyperline can attach calls to the wrong customer based on their addresses unless you exclude the domain. Hyperline validates the token immediately and rejects it if it is invalid or revoked. The integration appears as connected and Hyperline starts matching Grain recordings to Hyperline customers. The connection is read-only. Hyperline never creates, edits, or deletes anything in Grain. ## What Hyperline fetches For every matched recording, Hyperline stores: | Data | Details | | - | - | | Recording | Grain recording identifier and title | | Timing | Start and end date and time, and duration | | Participants | Name and email of each participant, and whether they attended | | Transcript | The transcript of the recording, when Grain has produced one | Hyperline does not download the video or audio files. Only the details and transcript listed above are stored. ### Summaries Grain does not provide a written summary through its API. When a transcript is available, Hyperline generates the meeting summary itself from that transcript. ### Which recordings are matched Grain cannot filter recordings by participant, so Hyperline scans the workspace and matches locally. A recording is attached to a customer when at least one participant email corresponds to: * the customer **Domain**, meaning any participant using an email address on that domain * the customer **Billing email** * one of the customer **Invoice emails** * a contact email synced from a connected CRM Hyperline does not store recordings that it cannot match to a customer. Keep customer **Domain** and **Billing email** values up to date. They are the main signals used to attach a Grain recording to the right customer. ## Synchronization Hyperline synchronizes Grain in two ways: * **Daily workspace synchronization**: once a day, Hyperline scans recent recordings and attaches the new ones to the matching customers. * **On-demand customer synchronization**: Hyperline also refreshes data when the customer monitoring agent analyzes a customer, and when you click **Sync meetings** from the customer's Grain panel. Synchronization is incremental. Recordings already stored are not fetched again, and a transcript already downloaded is never downloaded twice. Each run processes a bounded number of recordings and transcripts, so a Grain workspace with a large history is backfilled progressively over successive runs rather than in a single pass. ## Where Grain data appears * **Customer page**: the **Integrations** section shows a Grain row with the most recent meeting. Open it to browse synced meetings with their participants, summary, and transcript, or to trigger **Sync meetings**. * **Monitoring agent**: enable Grain from the agent's **Connectors** tab. See [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent). * **Analysis results**: Grain appears under **Data sources** when call context was used. ## Manage the integration Open **Settings > Integrations** and select **Grain**. Synchronization errors, such as a revoked token, are reported on this page. Use **Disconnect** to stop synchronizing new recordings. Revoke the access token in Grain as well if you want to invalidate it entirely. ## Related * [Claap](./claap) * [Customer intelligence](../docs/customer-intelligence/overview) * [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent) * [Integrations overview](./overview) # Granola Source: https://docs.hyperline.co/integrations/granola Connect Granola per user to bring meeting notes, participants, summaries, and transcripts into Hyperline for the customer monitoring agent. [Granola](https://www.granola.ai) is an AI notepad that sits in your meetings and turns them into notes, summaries, and transcripts. Connecting Granola lets Hyperline attach your customer meetings to the matching Hyperline customers. The customer monitoring agent can then combine what was said on a call with contract, subscription, invoice, payment, and usage data. Granola is part of [Customer intelligence](../docs/customer-intelligence/overview), a paid add-on. Contact the Hyperline team through the in-app chat to enable it. Granola is **user-scoped**: each teammate connects their own Granola API key from **Profile > Integrations**, not from the workspace-level **Settings > Integrations** page. Hyperline only sees the notes of the users who connected. ## Prerequisites * A [Granola account](https://www.granola.ai) with meeting notes. * A Granola API key, created from your Granola settings. You connect Granola for yourself, so no admin rights on your Hyperline account are needed. ## Connect Granola Before connecting, add your own company email domain (for example `yourcompany.com`) to **Settings > Customers > Excluded email domains**. CRMs often store your team members as contacts on customer records. Because your team joins every call, Hyperline can attach calls to the wrong customer based on their addresses unless you exclude the domain. Hyperline validates the key immediately and rejects it if it is invalid or revoked. The connection appears as active for your user, and Hyperline starts matching your Granola notes to Hyperline customers. The connection is read-only. Hyperline never creates, edits, or deletes anything in Granola. ## What Hyperline fetches For every matched note, Hyperline stores: | Data | Details | | - | - | | Meeting | Granola note identifier and title | | Timing | Start and end date and time, and duration, taken from the calendar event the note is attached to | | Participants | Name and email of the attendees, calendar invitees, organizer, and the teammate who recorded the note | | Summary | The summary Granola wrote for the meeting | | Transcript | The transcript, attributed by speaker, when Granola has produced one | Hyperline does not download the audio files. Only the details, summary, and transcript listed above are stored. A note taken outside a calendar event has no start, end, or duration to read, so Hyperline records the meeting without them. Granola also does not report which platform hosted the call, so no meeting source is stored. ### Which notes are matched A note is attached to a customer when at least one of its participants corresponds to: * the customer **Domain**, meaning any participant using an email address on that domain * the customer **Billing email** * one of the customer **Invoice emails** * a contact email synced from a connected CRM Hyperline does not store notes that it cannot match to a customer. Keep customer **Domain** and **Billing email** values up to date. They are the main signals used to attach a Granola note to the right customer. ## Synchronization Hyperline synchronizes Granola in three ways: * **Initial synchronization**: right after you connect your key. * **Daily synchronization**: once a day, for every user who connected a Granola key. * **On-demand synchronization**: Hyperline also refreshes data when the customer monitoring agent analyzes a customer. Synchronization is incremental. Notes already stored are not fetched again, and a transcript already downloaded is never downloaded twice. Each run scans a bounded number of recent notes and stays within Granola's rate limits. Hyperline backfills a Granola account with a large history progressively over successive runs rather than in a single pass. ## Where Granola data appears * **Customer page**: the **Integrations** section shows a Granola row with the most recent meeting when you connected your own key. Open it to browse synced meetings with their participants, summary, and transcript. * **Monitoring agent**: Granola has no toggle in the agent's **Connectors** tab, because it is connected per user rather than for the workspace. Its meetings reach the agent as soon as a teammate has connected their key. See [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent). * **Analysis results**: Granola appears under **Data sources** when call context was used. ## Manage the connection Open **Profile > Integrations** to review or remove your own connection. Disconnecting stops Hyperline from reading your notes. Revoke the API key in Granola as well if you want to invalidate it entirely. Each teammate manages their own connection, so removing yours does not affect anyone else's. ## Related * [Grain](./grain) * [Claap](./claap) * [Customer intelligence](../docs/customer-intelligence/overview) * [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent) * [Integrations overview](./overview) # Help Scout Source: https://docs.hyperline.co/integrations/help-scout Connect Help Scout with Hyperline to attach support conversations, tags, statuses, and messages to customers and surface support pressure to the agent. [Help Scout](https://www.helpscout.com) is a help desk platform that centralizes customer support conversations across shared mailboxes, chat, and email. Connecting Help Scout lets Hyperline attach support conversations to the matching Hyperline customers. The customer monitoring agent can then weigh unresolved issues and support pressure alongside contract, invoice, payment, and usage data. Help Scout is part of [Customer intelligence](../docs/customer-intelligence/overview), a paid add-on. The Help Scout card only appears in **Settings > Integrations** when Customer intelligence is enabled for your account. Contact the Hyperline team through the in-app chat to enable it. ## Prerequisites * A valid [Help Scout account](https://www.helpscout.com). * A Help Scout user allowed to authorize applications for your account, usually an administrator. * Admin rights on your Hyperline account. ## Connect Help Scout You are redirected to Help Scout. Sign in if needed, review the requested access, and confirm. You are redirected back to Hyperline and the integration appears as connected. ### Requested permissions Help Scout does not offer granular scopes on this flow. The grant is scoped to what the authorizing user can see, so connect with a user who has access to every mailbox your customers write to. Hyperline only reads conversations and their messages, and never sends, replies to, or modifies anything in Help Scout. The single exception is the webhook described below, which Hyperline registers and removes for you. ## What Hyperline fetches For every matched conversation, Hyperline stores: | Data | Details | | - | - | | Conversation | Help Scout conversation identifier, subject, and a short preview of the body | | Status | Normalized to `open` or `closed` | | Tags | The conversation tags, used as labels | | Customer | Name and email of the conversation's primary customer | | Dates | Creation date and last update date | | Messages | Each message with its body, author name and email, whether it came from the customer or an agent, and its date | Help Scout conversations have no priority concept, so every synced conversation carries the same default priority in Hyperline. Internal notes are synced alongside customer replies and stored as notes. Anything written on a conversation in Help Scout can therefore be used as context by the monitoring agent. ### Which conversations are matched Help Scout has no company or account entity, only customers keyed by email, so the customer **Domain** is the only signal available. Hyperline searches conversations mentioning that domain, then keeps only those whose primary customer uses an email address on it. Hyperline skips public email domains, such as `gmail.com`: a domain search on them would match unrelated conversations. Keep customer **Domain** values up to date. The domain is the only way a Help Scout conversation can be attached to the right customer. Each sweep reads the most recent conversations for a domain rather than the whole history, so a mailbox with years of conversations is not retrieved in full. ## Synchronization Hyperline synchronizes Help Scout in three ways: * **Daily synchronization**: once a day, for every customer with a domain. * **On-demand synchronization**: Hyperline refreshes data when the customer monitoring agent analyzes a customer. * **Webhook updates**: conversations are refreshed as they change, without waiting for the daily run. ### Webhook When you connect Help Scout, Hyperline registers a webhook in your Help Scout account labeled **Hyperline support sync**. It covers new conversations, status changes, tag changes, and customer or agent replies. Hyperline removes the webhook automatically when you disconnect the integration. Deleting it manually in Help Scout only stops the real-time refresh: the daily synchronization keeps running. ## Where Help Scout data appears * **Customer page**: the **Integrations** section shows a Help Scout row with the most recent thread. Open it to browse synced conversations with their statuses, labels, and messages. * **Monitoring agent**: enable Help Scout from the agent's **Connectors** tab. See [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent). * **Analysis results**: Help Scout appears under **Data sources** when support context was used. ## Manage the integration Open **Settings > Integrations** and select **Help Scout**. Synchronization errors, such as an expired authorization, are reported on this page. Use **Disconnect** to stop synchronizing new conversations and remove the Hyperline webhook. Help Scout offers no way for an application to revoke its own access. To invalidate the authorization entirely, also remove Hyperline from the authorized applications of your Help Scout account. ## Related * [Customer intelligence](../docs/customer-intelligence/overview) * [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent) * [Integrations overview](./overview) # Hightouch Source: https://docs.hyperline.co/integrations/hightouch Sync customer and revenue data from Hightouch into Hyperline reverse-ETL pipelines to power billing automation and finance workflows. ## What is Hightouch? [Hightouch](https://hightouch.com) is a platform that enables businesses to sync data between different systems, databases, or applications, often associated with data integration and synchronization. It facilitates the movement of data between various sources and destinations. This allows companies to streamline their operations, automate processes, and ensure that different tools or databases remain up-to-date with the most recent information. You can easily send all this data to Hyperline to collect your customer's usage and automate usage-based billing and invoicing. ## Send usage from Hightouch to Hyperline ### Configure a data source The first thing you need to create in Hightouch is a `source`. The source can be of any type (spreadsheet, database, warehouse, etc.). ### Create an HTTP Request destination Hyperline uses HTTP requests to ingest usage. Setting up this `destination` in Hightouch takes only a few clicks: You need to add two headers: * `Authorization` with `Bearer ` as a **secret** value * `Content-Type` with `application/json` as value ### Create a model After saving the destination, you need to create a `model` representing the entity you want to sync (represented as `event` in Hyperline). Put a name and select a primary key from the source fields. After finishing the model, you can also configure more settings on it like column types, descriptions, etc. ### Create a sync The last step you need to configure is a `sync`. Syncs declare how you want query results from a model to appear in your destination (Hyperline). Put a name and select a primary key from the source fields. Select **Row added** and **Row updated** triggers, **POST** HTTP request method, don't change the URL, **JSON** as type of payload with **Use JSON editor**. Here is an example of JSON payload that can be sent to the Hyperline ingest API. ```json theme={null} { "customer_id": "{{ row.customerId }}", "event_type": "{{ row.eventType }}", "timestamp": "{{ row.timestamp }}", "record": { "id": "{{ row.eventId }}", "my_property": "{{ row.customProperty }}", // add any custom properties you want to ingest in Hyperline }, } ``` Hightouch supports Liquid template language to insert variables from your source to your JSON payload. These variables are created following this syntax: `{{ row.variable }}`, `variable` being the column name of your source. Verify your synchronization by using a data sample. A new event should appear on your events [explore](https://app.hyperline.co/app/events/explore) page within Hyperline. When you're ready, activate this sync and specify a periodic trigger. # HubSpot Source: https://docs.hyperline.co/integrations/hubspot Connect HubSpot with Hyperline to sync deals, customers, contracts, and subscription data, and view customer intelligence directly in your CRM. The Hyperline-HubSpot integration lets you create and manage Hyperline quotes, subscriptions, and customers from a billing card in your CRM. Each action opens an embedded Hyperline interface. You can also enable data synchronization between Hyperline and HubSpot to use billing data in your CRM workflows and reports. ## Prerequisites You must have a valid [HubSpot account](https://hubspot.com) and access to the settings of your Hyperline account. Use a **test account** to test the integration before going live. You can create a free [HubSpot account](https://app.hubspot.com/signup-hubspot/crm) and use the [test mode](../docs/getting-started/sandbox) of your Hyperline account during setup and testing. ## Embedded Hyperline UIs in HubSpot ### Installation Upon connecting your HubSpot account to Hyperline, Hyperline automatically adds the Hyperline billing card to your HubSpot account. This card appears on your company and deal pages. Your revenue teams can keep using HubSpot while accessing all Hyperline functionalities. If the card isn't added automatically, you can add it manually. Open a company or deal record page and go to **Customize** > **Default view** (or any view) > **Edit layout**. In the right panel, hover over an existing card to reveal the option to add a new one. Select **Hyperline** and save your changes. ### Cards #### Billing card Once installed, you can use the billing card on **company**, **contact**, and **deal** pages (right side panel). You can: * Create Hyperline quotes. * Create Hyperline subscriptions. * Manage the linked Hyperline customer. Each action opens a Hyperline interface within HubSpot. ##### Settings You can configure the billing card from **Settings** > **Integrations** > **HubSpot**. ###### Root object Controls which HubSpot object the billing card treats as the source of truth when displaying Hyperline billing data (quotes and subscriptions). Two modes are available: * **Company**: All quotes and subscriptions of a company are displayed on both the company card and the cards of its related deals. Select this option if your revenue team thinks about billing at the customer level and wants the full billing picture available from any deal tied to that customer. * **Deal**: Only the quotes and subscriptions attached to a specific deal are displayed on that deal's card. The company card still shows all of the company's quotes and subscriptions. Select this option if you want each deal to surface only its own billing items, with no cross-deal bleed. This setting only affects what's displayed in the billing card. It does not change how data is synchronized with HubSpot custom objects. ###### Allow creating new customer When enabled, a HubSpot user can trigger an action from a company or deal that isn't yet linked to a Hyperline customer. The user can then create the corresponding Hyperline customer on the fly and proceed with the action. When disabled, actions are blocked until a matching Hyperline customer exists and is linked to the HubSpot record. ###### Display customers' children's data When enabled, the billing card also displays quotes and subscriptions belonging to the customer's children (in Hyperline's parent–child customer hierarchy), in addition to the customer's own. This is useful when you bill parent accounts but want visibility into activity across their subsidiaries from the parent's HubSpot record. #### Customer intelligence card The **Customer intelligence** card lets you review the linked Hyperline customer's latest monitoring result directly from the sidebar of a HubSpot company, contact, or deal record. It is a separate card from the Hyperline billing card. To add it to a record view: 1. Open a company, contact, or deal record and go to **Customize** > **Default view** (or the view you want to edit) > **Edit layout**. 2. Add the **Customer intelligence** card to the right sidebar and save your changes. When available, the card displays: * **Health score**: The customer's score out of 100, with a color indicating their health tier. * **Summary**: A summary of the customer monitoring analysis. * **Last run**: The date of the latest monitoring result. Click the **Customer intelligence** title to open the detailed monitoring result when one is available. If no score is available, the card shows the monitoring or analysis status, such as `pending`, `running`, or `failed`, or indicates that no run exists yet. Monitoring requires the [Customer Intelligence paid add-on](../docs/customer-intelligence/overview) and a [customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent). The CRM record must be linked to a Hyperline customer using the [reconciliation rules below](#data-reconciliation), and your Hyperline role must allow you to view customers. If prompted, use **Link customer** to associate the record with a Hyperline customer. ### User access You control how HubSpot users get access to Hyperline with the **Automatically register users** toggle in the **User access** section of **Settings** > **Integrations** > **HubSpot**. * **Enabled**: HubSpot users do not need an existing Hyperline account. When a user triggers a Hyperline action for the first time, Hyperline automatically creates a corresponding Hyperline user with their HubSpot email address. Hyperline assigns this user to your default Hyperline role (the ['Account manager' role](../docs/account/users-permissions#default-role) if not changed). * **Disabled**: Hyperline does not create users from HubSpot activity. Only HubSpot users who are already members of your Hyperline workspace can access Hyperline interfaces in HubSpot. [Invite users](../docs/account/users-permissions#invite-members) before they use the integration. If email matching domains are configured for your account, the **User access** section lists them. Hyperline matches a HubSpot user to an existing Hyperline user with the same email name (the part before the `@`) on any of these domains. For example, with `acme.com` and `acme.io` configured, `jane@acme.io` in HubSpot matches the existing Hyperline user `jane@acme.com`. These domains are read-only in the settings. Contact support to change them. When Hyperline interfaces open inside HubSpot, Hyperline applies the user's Hyperline role to ensure the correct view and edit permissions. You manage these permissions directly in Hyperline under **Settings** > **Team**. ### Data reconciliation Hyperline first determines which HubSpot record represents the customer. It then reconciles that record with a Hyperline customer. | Where you open the Hyperline card | Record used for reconciliation | | - | - | | Company | The company itself | | Contact associated with a company | The associated company | | Contact without an associated company | The contact itself | | Deal associated with a company | The associated company | | Deal without a company, but associated with a contact | The associated contact | For deals, Hyperline checks for an associated company first. It uses an associated contact only when no company is available. The deal identifies the sales opportunity but is not reconciled directly with a Hyperline customer. The **Root object** setting does not change this lookup order. It controls which quotes and subscriptions the billing card displays after Hyperline identifies the customer. After selecting the company or contact, Hyperline applies the following lookup mechanism: 1. If the HubSpot record is already linked to a Hyperline customer through the **Integrations** section of the customer page, Hyperline uses that customer. 2. If the record has a value in the Hyperline customer ID property, Hyperline looks for the corresponding customer. 3. If the record has a value in the Hyperline external ID property, Hyperline looks for a customer whose ID or external ID matches that value. It also checks for a customer whose linked Stripe customer ID matches that value (for example, a customer imported from Stripe). Company and contact links are separate. Even if a contact belongs to a company, linking the contact does not link the company automatically. For B2B customers, associate the contact or deal with the correct company so Hyperline reconciles through the company. Use direct contact reconciliation for B2C customers without an associated company. If the HubSpot record and the Hyperline customer were not previously linked, Hyperline automatically creates the link, provided the integration settings allow it. For companies, customer synchronization must be enabled, the direction must include HubSpot → Hyperline, and the company must be flagged for synchronization. If Hyperline finds a customer but the settings do not allow automatic linking, Hyperline surfaces the suggested customer in HubSpot, along with an action to manually trigger the link. If Hyperline finds no customer but the **Allow creating new customer** setting is enabled, the HubSpot user can create a new related Hyperline customer and proceed with the desired action. ## Data synchronization The integration can also synchronize data from Hyperline to HubSpot custom objects. This synchronization is optional, and you can configure it afterward. Data synchronization with custom objects is only available for HubSpot **companies** and **not for contacts**. Before enabling synchronization for an entity, create the required HubSpot custom objects described in the prerequisites below. Then select the entities you want to synchronize in **Settings** > **Integrations** > **HubSpot**. Deleting or manually modifying Hyperline custom objects and custom fields in HubSpot may break the integration and lead to unexpected behavior. Changing the data you select to synchronize requires reconfiguring the integration. This process may take a few minutes to complete. ### Prerequisites To synchronize data, Hyperline requires specific custom objects to exist in your HubSpot account. Hyperline does not have permission to automatically create custom objects in your HubSpot account. You must create them manually using the object internal names listed below. If a required custom object does not exist, you can't activate synchronization for that entity. Hyperline does not push any data to HubSpot for it. Custom objects are available only on the HubSpot **Enterprise** plan. For more details, see the [HubSpot documentation](https://knowledge.hubspot.com/object-settings/create-custom-objects). | Entity | HubSpot object internal name | | - | - | | Quote | `hyperline_quotes` | | Quote line item | `hyperline_quote_line_items` | | Quote coupon | `hyperline_quote_coupons` | | Quote phase | `hyperline_quote_phases` | | Quote file | `hyperline_quote_files` | | Subscription | `hyperline_subscriptions` | | Subscription product | `hyperline_subscription_products` | | Subscription coupon | `hyperline_subscription_coupons` | | Subscription phase | `hyperline_subscription_phases` | | Invoice | `hyperline_invoices` | | Invoice line item | `hyperline_invoice_line_items` | | Custom property value | `hyperline_custom_property_values` | To create the required custom objects: 1. Click the **Gear** icon (top-right corner). 2. Go to **Data Management** > **Objects** > **Custom Objects**. 3. Click the **Create Custom Object** button. 4. Enter the object details. Hyperline requires the **Internal name** to match one of the names listed in the table above. You may customize the display name as you prefer. 5. Repeat this process for each object you want to synchronize. Object `Internal name` **must match the required name** (HubSpot object internal name) listed above. Each custom object **must include a mandatory `name` field** of type `text`. The red sections must match the requirements; otherwise, the integration will fail. Create only the custom objects required for the entities you want to synchronize. ### Mapping Below are the default field mappings between Hyperline entities and HubSpot objects. Field mappings between Hyperline entities and HubSpot objects ### Customer sync When enabled, Hyperline synchronizes customers with HubSpot companies. You can select the synchronization direction (one-way or bidirectional). During the integration setup, Hyperline creates a **(Hyperline) Synchronize** checkbox custom field (`hyperline_sync` slug) on the Company object. Hyperline imports and synchronizes a HubSpot company only when this checkbox is enabled. Hyperline ignores companies without it checked. #### Customer custom properties Customer custom properties use different paths for inbound and outbound synchronization: * **From HubSpot company properties to Hyperline**: Create a property on the HubSpot Company object whose internal name exactly matches the Hyperline custom property `slug`. When you synchronize customers from HubSpot, Hyperline imports this value into the matching existing customer custom property. Changes in Hyperline do not update this HubSpot property. * **From Hyperline to custom property value records**: Enable **Custom property values** in the integration settings. Hyperline creates one record in the `hyperline_custom_property_values` custom object for each value and associates customer values with the related HubSpot company. This option also keeps each property's name, type, and value available as separate fields. If a Hyperline customer custom property uses the `customer_tier` slug, create a HubSpot company property with `customer_tier` as its internal name. Set its value in HubSpot to import it into Hyperline when the customer syncs. The matching HubSpot company property must already exist, and the integration must be able to read it. Hyperline does not create it automatically. Synchronizing values through the custom object requires HubSpot Enterprise and the `hyperline_custom_property_values` object described above. #### Turn customer fields on or off You can select which default customer fields Hyperline syncs. To stop syncing specific fields, for example if you manage the currency or billing address only in HubSpot, configure the customer field mappings. 1. In the HubSpot integration settings, go to the customer synchronization section. 2. Click **Configure field mappings**. 3. In the **Customer field mappings** modal, use the toggle next to each field to turn its sync on or off. Each field shows its fixed HubSpot destination (company property) below its name. 4. Click **Save changes**. Changes apply in the sync direction you configured. Disabled fields keep their existing values. Click **Cancel** to close the modal without saving. You can't turn off fields that Hyperline needs to identify and link customers. Their toggles are locked. Creating new customers may still require some fields to be synced. ### Quote sync When **Quotes** is enabled, Hyperline pushes quotes to the `hyperline_quotes` custom object. You can also enable **Quotes line items**, **Quotes coupons**, **Quotes phases**, and **Quotes files** to push the related data to their own custom objects, associated with the quote. Hyperline syncs line items and coupons only for subscription quotes (new subscriptions and subscription updates). One-off quotes don't sync line items or coupons. #### Products and line items Each active product of the quote's subscription becomes a quote line item record in HubSpot. Hyperline doesn't sync products removed from the subscription. Which products and coupons Hyperline syncs depends on the **Quotes phases** setting: * **Quotes phases enabled**: Hyperline syncs the products and coupons of every phase of the quote. Hyperline associates each line item and coupon with its quote phase record in HubSpot. * **Quotes phases disabled**: Hyperline only syncs the products and coupons of the first phase. Hyperline doesn't push products and coupons from later phases to HubSpot. With **Quotes phases** enabled on a subscription update quote, Hyperline only syncs the upcoming phases introduced by the update, not the phases that already started. A quote includes two phases: a 3-month ramp-up phase at a discounted price, followed by a 12-month phase at the full price. With **Quotes phases** disabled, HubSpot only receives the line items and coupons of the ramp-up phase. Enable **Quotes phases** to get the line items and coupons of both phases. ### Manually trigger a sync You can also manually trigger customer data synchronization from the Hyperline customer page. In the **Integrations** dropdown, click **Sync with HubSpot** to push (or pull, depending on the sync direction) the customer's data. Hyperline also sends all associated quotes, subscriptions, and invoices to HubSpot. ## Custom workflows Beyond the built-in synchronization, you can build your own automations in HubSpot by reacting to Hyperline [webhooks](../api-reference/docs/webhooks). A few examples of what this unlocks: * Update HubSpot deal fields (stage, close date, amount, custom properties) when a Hyperline quote is signed or voided. * Compute and write custom metrics (ARR, MRR, committed amount, contract length) on the company or deal once a subscription is activated or renewed. * Trigger HubSpot tasks, internal notifications, or Slack alerts when an invoice becomes late or a subscription is cancelled. * Move deals along your pipeline when subscription contracts start, renew, or expire. ### How it works 1. In Hyperline, create a webhook endpoint in **Settings** > **Webhooks** and subscribe to the events you care about (e.g. `quote.signed`, `subscription.activated`, `subscription.contract_renewed`, `invoice.settled`). See the full list in the [Webhooks](../api-reference/docs/webhooks) reference. 2. In HubSpot, expose an endpoint that receives the Hyperline payload. The most common patterns are: * A HubSpot workflow webhook trigger: use the Hyperline event to start a workflow that updates fields, sends notifications, or branches based on payload data. * A custom-coded action (HubSpot Operations Hub) or an external service (Zapier, n8n, your own backend) that calls the HubSpot API to update the relevant company or deal. 3. Use the Hyperline customer ID or HubSpot company ID from the webhook payload to resolve the correct HubSpot record, then apply your business logic. Hyperline webhooks are signed. Verify the signature before acting on a payload. Details are in the [Webhooks](../api-reference/docs/webhooks) reference. ## Troubleshooting If data is missing or synchronization fails, open **Settings** > **Integrations** > **HubSpot** > **View issues** in Hyperline for details. ### Common issues **Embedded Hyperline views don't load, or an action loads forever** This happens when your browser blocks third-party cookies, which Hyperline needs to authenticate the embedded view inside your CRM. Allow third-party cookies for `[*.]hyperline.co`, then reload the page: Browsers block links to settings pages, so the addresses below aren't clickable. Copy the address and paste it into a new browser tab. * **Chrome / Arc**: open `chrome://settings/cookies`, then under "Sites allowed to use third-party cookies" add `[*.]hyperline.co` (or select "Allow all cookies"). See [Google's guide](https://support.google.com/chrome/answer/95647). * **Edge**: open `edge://settings/content/cookies` and add `[*.]hyperline.co` under "Allow". See [Microsoft's guide](https://support.microsoft.com/microsoft-edge/temporarily-allow-cookies-and-site-data-in-microsoft-edge-597f04f2-c0ce-f08c-7c2b-541086362182). * **Safari**: open Settings > Privacy and uncheck "Prevent cross-site tracking". See [Apple's guide](https://support.apple.com/guide/safari/manage-cookies-sfri11471). * **Firefox**: click the shield icon in the address bar and turn off "Enhanced Tracking Protection" for this site, or add an exception under Settings > Privacy & Security. See [Mozilla's guide](https://support.mozilla.org/kb/enhanced-tracking-protection-firefox-desktop). Also disable any browser extension that blocks cookies or trackers for this site. **The HubSpot billing card is empty (only the buttons appear, with no data)** This issue usually occurs when the same HubSpot ID is assigned to multiple customers in Hyperline. Hyperline uses the first matching customer it finds, but that customer may not contain any data. Ensure that the HubSpot ID is assigned to only one customer in Hyperline: the correct one. ## Disconnect You can disconnect the integration at any time by clicking **Disconnect** in the top-right corner of the HubSpot integration settings page. Disconnecting the integration stops all synchronization. The custom objects, custom fields, and any previously pushed data in HubSpot remain intact. Hyperline does not delete them. # Intercom Source: https://docs.hyperline.co/integrations/intercom Connect Intercom with Hyperline to bring customer conversations, statuses, tags, and messages into customer intelligence analyses. [Intercom](https://www.intercom.com) is a customer communication platform combining in-app messaging, email, and a help desk. Connecting Intercom lets Hyperline attach customer conversations to the matching Hyperline customers. The customer monitoring agent can then weigh unresolved issues and support pressure alongside contract, invoice, payment, and usage data. Intercom is part of [Customer intelligence](../docs/customer-intelligence/overview), a paid add-on. The Intercom card only appears in **Settings > Integrations** when Customer intelligence is enabled for your account. Contact the Hyperline team through the in-app chat to enable it. ## Prerequisites * A valid [Intercom account](https://www.intercom.com). * An Intercom access token, created from your Intercom developer settings. * Admin rights on your Hyperline account. ## Connect Intercom Hyperline validates the token immediately and rejects it if it is invalid or revoked. The integration appears as connected and Hyperline starts matching Intercom conversations to Hyperline customers. The connection is read-only. Hyperline never sends, replies to, or modifies anything in Intercom. ## What Hyperline fetches For every matched conversation, Hyperline stores: | Data | Details | | - | - | | Conversation | Intercom conversation identifier, title, and a short preview of the opening message | | Status | Normalized to `open`, `closed`, or `snoozed` | | Priority | Whether Intercom flagged the conversation as a priority | | Tags | The conversation tags, used as labels | | Contact | Email and name of the contact on the conversation | | Dates | Creation date and last update date | | Messages | Each conversation part with its text, author name and email, and date | Internal notes are synced alongside customer-facing replies and stored as notes. Anything written on a conversation in Intercom can therefore be used as context by the monitoring agent. ### Which conversations are matched Hyperline resolves conversations in two steps. First it finds the Intercom contacts belonging to the customer: 1. If the customer is linked to an Intercom **company**, Hyperline lists that company's contacts. 2. Otherwise, Hyperline searches contacts whose email address is on the customer **Domain**. It then retrieves the conversations belonging to those contacts. Hyperline skips public email domains, such as `gmail.com`: a contact search on them would match unrelated conversations. Keep customer **Domain** values up to date, and link the Intercom company on the customer page when you have one. The company link is the more precise of the two. ## Synchronization Hyperline synchronizes Intercom once a day, and also refreshes a customer on demand when the customer monitoring agent analyzes it. ## Where Intercom data appears * **Customer page**: the **Integrations** section shows an Intercom row with the most recent thread. Open it to browse synced conversations with their statuses, labels, and messages. * **Monitoring agent**: enable Intercom from the agent's **Connectors** tab. See [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent). * **Analysis results**: Intercom appears under **Data sources** when support context was used. ## Manage the integration Open **Settings > Integrations** and select **Intercom**. Synchronization errors, such as a revoked token, are reported on this page. Use **Disconnect** to stop synchronizing new conversations. Revoke the access token in Intercom as well if you want to invalidate it entirely. ## Related * [Customer intelligence](../docs/customer-intelligence/overview) * [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent) * [Integrations overview](./overview) # Jiminny Source: https://docs.hyperline.co/integrations/jiminny Connect Jiminny with Hyperline to sync call recordings, participants, summaries, and transcripts into customer intelligence analyses and reports. [Jiminny](https://www.jiminny.com) is a conversation intelligence platform that records, transcribes, and analyzes customer calls, including video meetings and calls placed from its dialer. Connecting Jiminny lets Hyperline attach your recorded customer conversations to the matching Hyperline customers. The customer monitoring agent can then combine what was said on a call with contract, subscription, invoice, payment, and usage data. Jiminny is part of [Customer intelligence](../docs/customer-intelligence/overview), a paid add-on. The Jiminny card only appears in **Settings > Integrations** when Customer intelligence is enabled for your account. Contact the Hyperline team through the in-app chat to enable it. ## Prerequisites * A valid [Jiminny account](https://www.jiminny.com) with conversations recorded in your workspace. * A Jiminny **API key**, created from your Jiminny organization settings. Generating one usually requires a Jiminny administrator. * Admin rights on your Hyperline account. The key is issued at organization level and covers every recording in your Jiminny workspace. Hyperline attributes conversations to customers across the whole organization, so a key limited to a single user would only ever surface that user's calls. ## Connect Jiminny Before connecting, add your own company email domain (for example `yourcompany.com`) to **Settings > Customers > Excluded email domains**. CRMs often store your team members as contacts on customer records. Because your team joins every call, Hyperline can attach calls to the wrong customer based on their addresses unless you exclude the domain. Open your Jiminny organization settings, go to **Integrations**, and generate a key for the Customer API. Copy it immediately, as Jiminny only displays it once. Hyperline validates the key immediately and rejects it if it is invalid or revoked. The integration appears as connected and Hyperline starts matching Jiminny conversations to Hyperline customers. Jiminny runs separate instances for different regions, and a key is only valid on the one that issued it. Hyperline detects the right instance while validating the key, so there is nothing to select. The connection is read-only. Hyperline never creates, edits, or deletes anything in Jiminny. ## What Hyperline fetches For every matched conversation, Hyperline stores: | Data | Details | | - | - | | Conversation | Jiminny conversation identifier, title, and the conferencing tool behind the recording | | Timing | Start and end date and time, and duration | | Participants | Name and email address of each participant, internal and external, and whether they joined | | Summary | The summary Jiminny produced for the conversation | | Transcript | The transcript of the conversation, attributed to each speaker | Hyperline does not download audio or video recordings. Only the details, summary, and transcript listed above are stored. ### Which conversations are considered Hyperline syncs completed conversations that carry a recording: video meetings recorded by Jiminny, and inbound or outbound calls placed through the Jiminny dialer. Hyperline ignores SMS messages sent from the dialer, since they have nothing to transcribe. Very short conversations, such as an unanswered ring or a voicemail, are stored without a transcript. Jiminny does not produce one when there is no conversation to transcribe. ### Which conversations are matched Jiminny cannot filter conversations by participant, so Hyperline scans the organization and matches locally. A conversation is attached to a customer when at least one participant email corresponds to: * the customer **Domain**, meaning any participant using an email address on that domain * the customer **Billing email** * one of the customer **Invoice emails** * a contact email synced from a connected CRM Hyperline does not store conversations that it cannot match to a customer. Keep customer **Domain** and **Billing email** values up to date. They are the main signals used to attach a Jiminny conversation to the right customer. ### Summaries When Jiminny has produced a summary for a conversation, Hyperline uses it as the meeting summary. When a transcript is available but Jiminny has not produced a summary, Hyperline generates one from the transcript. ## Synchronization Hyperline synchronizes Jiminny in two ways: * **Daily workspace synchronization**: once a day, Hyperline reviews recent Jiminny conversations and attaches the new ones to the matching customers. * **On-demand customer synchronization**: Hyperline also refreshes data when the customer monitoring agent analyzes a customer, and when you click **Sync meetings** from the customer's Jiminny panel. Synchronization is incremental. Conversations already stored are not fetched again, and a transcript already downloaded is never downloaded twice. Jiminny builds transcripts and summaries after a call ends, so a conversation recorded a few minutes ago can appear before its transcript is available. Hyperline retrieves it on a later run, once Jiminny has finished generating it. The first synchronization covers up to 180 days of history, and each run processes a bounded number of conversations and transcripts. A Jiminny organization with a large history is therefore backfilled progressively over successive runs rather than in a single pass. ## Where Jiminny data appears * **Customer page**: the **Integrations** section shows a Jiminny row with the most recent meeting. Open it to browse synced meetings with their participants, summary, and transcript, or to trigger **Sync meetings**. * **Monitoring agent**: enable Jiminny from the agent's **Connectors** tab to let it use call context. See [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent). * **Analysis results**: Jiminny appears under **Data sources** when call context was used for an analysis. ## Manage the integration Open **Settings > Integrations** and select **Jiminny** to review the connection status. Synchronization errors, such as a revoked key, are reported on this page. Use **Disconnect** to stop synchronizing new conversations. Revoke the API key in Jiminny as well if you want to invalidate it entirely. ## Related * [Gong](./gong) * [Customer intelligence](../docs/customer-intelligence/overview) * [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent) * [Integrations overview](./overview) # Modjo Source: https://docs.hyperline.co/integrations/modjo Connect Modjo with Hyperline to sync call recordings, participants, summaries, and transcripts into customer intelligence analyses and reports. [Modjo](https://www.modjo.ai) is a conversation intelligence platform that records, transcribes, and analyzes customer calls and video meetings. Connecting Modjo lets Hyperline attach your recorded customer conversations to the matching Hyperline customers. The customer monitoring agent can then combine what was said on a call with contract, subscription, invoice, payment, and usage data. Modjo is part of [Customer intelligence](../docs/customer-intelligence/overview), a paid add-on. The Modjo card only appears in **Settings > Integrations** when Customer intelligence is enabled for your account. Contact the Hyperline team through the in-app chat to enable it. ## Prerequisites * A valid [Modjo account](https://www.modjo.ai) with calls recorded in your workspace. * A Modjo **Public API key**, created from your Modjo settings. Modjo restricts key creation to the Administrator and Manager roles. * Admin rights on your Hyperline account. The key is issued at workspace level and covers every call in your Modjo workspace. Hyperline attributes calls to customers across the whole workspace, so a credential limited to a single user would only ever surface that user's calls. ## Connect Modjo Before connecting, add your own company email domain (for example `yourcompany.com`) to **Settings > Customers > Excluded email domains**. CRMs often store your team members as contacts on customer records. Because your team joins every call, Hyperline can attach calls to the wrong customer based on their addresses unless you exclude the domain. Open your Modjo settings, go to **Integrations > Public API**, and generate a key. Copy it immediately, as Modjo only displays it once. Hyperline validates the key immediately and rejects it if it is invalid or revoked. If Modjo cannot be reached at that moment, Hyperline asks you to try again instead of reporting the key as invalid. The integration appears as connected and Hyperline starts matching Modjo calls to Hyperline customers. The connection is read-only. Hyperline never creates, edits, or deletes anything in Modjo. ## What Hyperline fetches For every matched call, Hyperline stores: | Data | Details | | - | - | | Call | Modjo call identifier and title | | Timing | Start date and time, duration, and the resulting end time | | Participants | Name and email address of each participant, both internal users and external contacts | | Summary | The summary Modjo produced for the call | | Transcript | The transcript of the call, attributed to each speaker | Hyperline does not download audio or video recordings. Only the details, summary, and transcript listed above are stored. ### Which calls are considered Hyperline syncs calls recorded in your Modjo workspace, whether they come from a video meeting or from a call placed in Modjo. A call Modjo is still processing is stored without a transcript, and Hyperline retrieves it on a later run once Modjo has finished generating it. A call whose transcript Modjo has deleted under your retention policy is kept as a meeting record, without transcript. ### Which calls are matched Modjo cannot filter calls by participant, so Hyperline scans the workspace and matches locally. A call is attached to a customer when at least one participant email corresponds to: * the customer **Domain**, meaning any participant using an email address on that domain * the customer **Billing email** * one of the customer **Invoice emails** * a contact email synced from a connected CRM Hyperline does not store calls that it cannot match to a customer. Keep customer **Domain** and **Billing email** values up to date. They are the main signals used to attach a Modjo call to the right customer. ### Summaries Modjo produces one summary per summary template configured in your workspace, so a single call can carry several. Hyperline keeps the most detailed one. When a transcript is available but Modjo has not produced a summary, Hyperline generates one from the transcript. ## Synchronization Hyperline synchronizes Modjo in three ways: * **On connection**: a first synchronization starts as soon as the integration is connected, so recent calls appear without waiting for the next daily run. * **Daily workspace synchronization**: once a day, Hyperline reviews recent Modjo calls and attaches the new ones to the matching customers. * **On-demand customer synchronization**: Hyperline also refreshes data when the customer monitoring agent analyzes a customer, and when you click **Sync meetings** from the customer's Modjo panel. Synchronization is incremental. Once a first run has stored calls, later runs only look at what is newer, and a transcript already downloaded is never downloaded twice. The first run covers the history available in your workspace, keeping the most recent calls, and each run fetches a bounded number of transcripts. A Modjo workspace with a large history is therefore backfilled progressively over successive runs rather than in a single pass. ## Where Modjo data appears * **Customer page**: the **Integrations** section shows a Modjo row with the most recent meeting. Open it to browse synced meetings with their participants, summary, and transcript, or to trigger **Sync meetings**. * **Monitoring agent**: enable Modjo from the agent's **Connectors** tab to let it use call context. See [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent). * **Analysis results**: Modjo appears under **Data sources** when call context was used for an analysis. ## Manage the integration Open **Settings > Integrations** and select **Modjo** to review the connection status. Synchronization errors, such as a revoked key, are reported on this page. Use **Disconnect** to stop synchronizing new calls. Revoke the API key in Modjo as well if you want to invalidate it entirely. ## Related * [Jiminny](./jiminny) * [Gong](./gong) * [Customer intelligence](../docs/customer-intelligence/overview) * [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent) * [Integrations overview](./overview) # Mollie Source: https://docs.hyperline.co/integrations/mollie Collect card and local payment method transactions through Mollie on Hyperline with one-click connection and automatic invoice reconciliation. ## Prerequisites You need to have a [Mollie account](https://my.mollie.com/dashboard), finished Mollie's onboarding flow, and admin rights on Hyperline. ## Setup If [Mollie](https://www.mollie.com) is your preferred Payment Service Provider, connecting it with Hyperline is a straightforward process: 1. In the menu, select **Settings** 2. Select **Payment** 3. Click **Connect payment provider**, then Mollie This will redirect you to the Mollie login page where you will have to enter your account credentials and click **Continue**. By default, we use the first [Mollie profile](https://my.mollie.com/dashboard/settings/profiles) available on your Mollie account. If you have multiple profiles and want to use a specific one, please contact our support. Once the process is completed, you will see Mollie appearing as **Active** in the Payment page. You can connect multiple Mollie accounts to Hyperline so that payments are routed based on your invoicing entities and preferences. ## Payment methods Mollie through Hyperline supports: * **Card** payments * **Direct Debit** payments with SEPA (EU) ## Customer information Each time you bill a customer in Hyperline, the corresponding customer profile and payment details (including payment methods and mandates) are automatically created and managed by Hyperline in your Mollie account. Additionally, Hyperline integrates payment method collection forms into our hosted pages (checkout, customer portal, invoice page, and quote page), requiring no technical effort on your part. This seamless integration ensures that customer data and payments remain synchronized between Hyperline and Mollie, streamlining transaction management and customer information handling. If you already have a Mollie account with existing customers and payment methods, you have the possibility **to import them in Hyperline**. It is particularly useful when you configure your account. Please contact support if you are interested. # NetSuite Source: https://docs.hyperline.co/integrations/netsuite Connect NetSuite to synchronize customers, invoices, credit notes, payments, refunds, chargebacks, and wallet activity from Hyperline. [NetSuite](https://www.netsuite.com) is Oracle's cloud-based ERP and accounting platform. Hyperline connects to NetSuite so your finance team can send billing data from Hyperline to NetSuite without manually recreating customers, invoices, credit notes, payments, refunds, or chargebacks. This guide covers the native NetSuite integration. Legacy NetSuite connections can have different settings. ## What Hyperline synchronizes The NetSuite integration is a one-way accounting synchronization from Hyperline to NetSuite. Hyperline also reads NetSuite metadata, such as subsidiaries, items, accounts, tax codes, and custom fields, so you can configure mappings from the Hyperline interface. | Hyperline data | What happens in NetSuite | | - | - | | Customers | Customers can be linked manually or created automatically when needed, depending on your customer synchronization setting. | | Invoices | Eligible Hyperline invoices are created as NetSuite **Invoice** records with the invoice currency and exchange rate when available. | | Credit notes | Hyperline credit notes are created as NetSuite **Credit Memo** records with the credit note currency and exchange rate when available. They can be applied to the original invoice when the credit note is linked to one. | | Invoice write-offs | When uncollectible invoice synchronization is enabled, Hyperline creates a **Journal Entry** debiting the mapped **Write-off debit account** and crediting the invoice's A/R account. A zero-amount **Customer Payment** applies the journal credit to the original invoice. | | Payments | Settled payments are created as NetSuite **Customer Payment** records when the payment method is configured to synchronize. | | Refunds | Settled refunds are created as NetSuite **Customer Refund** records when the payment method is configured to synchronize. | | Chargebacks | Chargebacks are created as NetSuite **Customer Refund** records applied to the original Customer Payment when the payment method is configured to synchronize. | | Wallet top-ups and wallet refunds | Paid wallet top-ups are synchronized as customer payments. Credit notes refunded to the wallet are applied to the original invoice and reflected in NetSuite by adjusting the related Customer Payment applications. Free wallet credits are not synchronized as payments. | NetSuite does not send accounting changes back to Hyperline through this integration. Keep Hyperline as the source for billing documents and payments that should be synchronized. ## Prerequisites Before connecting NetSuite, make sure you have: * A NetSuite account with **SuiteTalk REST Web Services**, **Token-Based Authentication**, and **SuiteAnalytics Workbook** enabled. * A NetSuite **Integration record** and access token for the user or role used by Hyperline. * Admin rights in Hyperline. * NetSuite subsidiaries, items, accounts, and tax codes ready for the Hyperline entities you plan to synchronize. * Hyperline products, sync rules, tax settings, and invoicing entities configured. ### NetSuite role and permissions Use a dedicated integration user and custom role. Configure and test that role in each NetSuite environment. A test using **Administrator** does not validate a custom role, even in the same account. #### Base API permissions In **Setup > Users/Roles > Manage Roles**, create or edit the integration role and assign: | Permissions tab | Permission | Level | | - | - | - | | Setup | REST Web Services | Full | | Setup | Log in using Access Tokens | Full | | Reports | SuiteAnalytics Workbook | Edit | These are [Oracle's REST Web Services prerequisites](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_5085602973.html). They allow API access but do not grant access to every record or custom-field definition. The administrator creating the access token needs the appropriate token-management permission. **Access Token Management** and **User Access Tokens** concern token creation and management; they are separate from the integration role's **Log in using Access Tokens** permission. See [Oracle's token-management instructions](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_4254975694.html). #### Record access Use this table to configure the role for the operations your integration performs. The levels reflect the read, create, update, and delete operations in Hyperline's integration; they are not a certification that the role will work with every NetSuite customization. Complete the [validation checklist](#validate-before-going-live) before going live. | Permissions tab | Permission | Level for the integration | Used for | | - | - | - | - | | Lists | Customers | Edit when creating or updating customers; View for lookup only | Customer linking and synchronization. | | Transactions | Invoice | Edit | Reading, creating, and updating invoices, including credit-note reversal invoices. | | Transactions | Credit Memo | Edit | Reading, creating, and updating credit notes and their applications. | | Transactions | Customer Payment | Full for flows that remove payments; otherwise Edit | Payments, allocations, wallet applications, and write-off applications. | | Transactions | Customer Refund | Full for flows that remove refunds; otherwise Edit | Refunds, chargebacks, and removal of cleared chargebacks or deleted refund records. | | Transactions | Make Journal Entry | Full for write-off creation and cleanup | Write-off journals; cleanup may delete the journal after removing its payment application. | | Lists | Subsidiaries | View | Invoicing entity mappings and subsidiary hierarchy. | | Lists | Items | View | Product and rounding-item mappings. | | Lists | Accounts | View | GL account mappings. | | Lists | Currency | View | Customer and transaction currencies. | | Lists | Tax Records | View | Sales tax items and tax groups. | | Lists | Tax Details Tab | Edit when using Hyperline tax amounts | Override SuiteTax details on invoices and credit memos. | | Setup | Manage Accounting Periods | View | Posting-period selection and deletion checks. | | Setup | Accounting Lists | View | Payment-method lookup when resolving a customer refund's payment method. | | Lists | Locations, Departments, Classes | View for each dimension used | Location lists and mapped reference values. | | Setup | Custom Lists | View when reference mappings use custom lists | Custom-list definitions and mapped values. | | Setup | Custom Record Types | View when reference mappings use custom records | Custom-record-type definitions. Also grant read access to the particular custom records referenced by a mapping. | NetSuite's [permission reference](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/chapter_N3236764.html) lists permission names and valid levels. In its [general access model](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N326341.html), **Edit** includes creation and updates, while **Full** also allows deletion. Account restrictions and record-specific rules still apply. The role must also be able to search the records above through SuiteQL. Validate the transaction and list lookups used by the integration, including transaction lines and links between transactions. NetSuite provides **Transactions > Find Transaction** and **Lists > Perform Search** permissions; see [Oracle's search permission documentation](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N664557.html). These do not replace access to the underlying records or custom-field metadata. Limit subsidiary access to the entities you plan to synchronize. Confirm that the role can see their customers, parent subsidiaries used for item availability, items, accounts, currencies, tax codes, and mapped reference values. A permission can be present while a role restriction still hides the record. For write-offs, configure journal approval in NetSuite. If a journal requires approval, approve it in NetSuite and retry the synchronization. Granting permission to create a journal does not bypass its approval workflow. #### Custom fields and metadata access For each mapped field, the integration role must be able to read its definition and write its value on the destination record. For list or record fields, it must also be able to read the referenced values. Review the field's **Access** settings, including role, department, subsidiary, and search/reporting restrictions. See [Oracle's custom-field access documentation](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N2841053.html). The integration uses NetSuite's standard **CustomField** metadata table through SuiteQL. Access to customers or invoices does not by itself prove access to this table. A role can connect successfully but fail field discovery or synchronization with **Record 'customfield' was not found**. Field search can then show **No results** even when the field exists. Hyperline has not yet verified the minimum additional permission that exposes this table to a restricted role. **Custom Entity Fields**, **Custom Body Fields**, and **Custom Column Fields** must not be treated as a confirmed fix for this error. If you encounter it, contact Hyperline through the in-app chat before going live. Metadata access also matters when you have not configured optional mappings: synchronization checks whether optional Hyperline URL and line-item fields exist. For reference mappings, the integration may also read custom-list, custom-record-type, and record-type definitions. See the [advanced access checklist](./netsuite-advanced#metadata-and-query-access) for the resources to validate. #### Validate before going live 1. In NetSuite, verify the **user and role selected on the access token** used by Hyperline. Checking the user's other assigned roles is not sufficient. 2. In Sandbox, connect with the intended custom integration role. Verify subsidiary, item, account, and tax-code lists for every configuration you use. 3. Search for a known field in each mapping category you use: **Customer**, **Invoice**, and **Invoice line**. Confirm the expected label and internal field ID. 4. Synchronize a test customer, invoice, and credit note with your required mappings. Check values and GL impact on the resulting NetSuite records, including the income or deferred revenue account configured on each item. 5. Test enabled payment, refund, chargeback, wallet, and write-off flows, including allocation changes and cleanup of records where applicable. Check journal approval and posting-period behavior. 6. Configure the equivalent role and restrictions in Live, create a Live access token, and repeat the read-only mapping checks with that connection. Sandbox tokens and Administrator tests do not validate Live access. Validate a controlled initial synchronization before a bulk resync. A successful connection only verifies authentication and a basic query. It does **not** check all record permissions, custom-field discovery, writes, deletions, approvals, or subsidiary restrictions. Live and Sandbox tokens are managed separately; see [Oracle's environment guidance](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_4254975694.html). ## Setup In NetSuite, go to **Setup > Company > Enable Features > SuiteCloud** and enable **Token-Based Authentication** and **SuiteTalk (REST Web Services)**. On the **Analytics** tab, enable **SuiteAnalytics Workbook**. In NetSuite, go to **Setup > Integrations > Manage Integrations > New**, create an enabled integration record for Hyperline, and enable **Token-Based Authentication**. NetSuite shows the **Consumer Key** and **Consumer Secret** only once. Copy both values and store them securely. Create or edit a dedicated custom role with the [NetSuite role and permissions](#netsuite-role-and-permissions) listed above, then assign it to the integration user. In NetSuite, go to **Setup > Users/Roles > Access Tokens > New** and create a token for the Hyperline integration record, user, and role. NetSuite shows the **Token ID** and **Token Secret** only once. Copy both values and store them securely. In Hyperline, open **Settings > Integrations**, select **NetSuite**, then enter your **Account ID**, **Consumer Key**, **Consumer Secret**, **Token ID**, and **Token Secret**. On **Settings > Integrations > NetSuite**, link each Hyperline invoicing entity to the matching NetSuite subsidiary. Map customers, products, accounts, tax codes, payment behavior, and optional custom fields. See [Configure mappings](#configure-mappings). ## Configure mappings ### Subsidiaries NetSuite requires a subsidiary on every customer and transaction. Map each Hyperline invoicing entity to a NetSuite subsidiary on **Settings > Integrations > NetSuite**. In OneWorld accounts, subsidiary mapping also controls which NetSuite items, accounts, and tax codes are available when you configure the rest of the integration. ### Customers If a customer already exists in NetSuite, you can link it to the matching Hyperline customer: 1. Open the customer in Hyperline. 2. Go to the **Integrations** section. 3. Click **Edit**. 4. Enter the NetSuite customer internal ID. 5. Click **Save**. For bulk linking during onboarding, contact our support team or use the [bulk provider mapping API](../api-reference/endpoints/customers/bulk-update-providerscustomers-mapping.mdx). You can select whether Hyperline should create missing NetSuite customers automatically: * **No synchronization**: you must link the customer manually before Hyperline can push its invoices. * **From Hyperline to NetSuite**: Hyperline creates the NetSuite customer the first time an invoice, credit note, payment, refund, or chargeback needs it. ### Products and items Every synchronized invoice line must have a NetSuite item. For each Hyperline product, open the product page, go to the **Accounting** section, and select the matching NetSuite item. Hyperline fetches items from NetSuite and filters the list based on the subsidiary mapped to the invoicing entity. If a product is missing an item mapping, the invoice synchronization stops with an issue you can fix and retry. Configure income accounts, deferred revenue accounts, and revenue recognition rules on the items in NetSuite. Hyperline maps products to existing items; it does not create items or override their revenue accounts or recognition rules on invoice and credit note lines. For example, to post setup fees and recurring subscriptions to different revenue accounts, configure two NetSuite items with the appropriate accounts and map each Hyperline product to its corresponding item. #### Coupon discount lines When an invoice or credit note includes coupons, Hyperline sends each coupon discount to NetSuite as a separate line below the impacted product line. This makes discounts easier to trace in NetSuite reports, revenue recognition, and journals. Each coupon discount line uses: * The same NetSuite item as the impacted product line. * The same tax code as the impacted product line. Revenue accounts and recognition rules follow the NetSuite item's configuration. * A negative amount that offsets the gross product line amount. * A description that includes the coupon name, product name, and service period when available. When a coupon applies to multiple invoice lines, Hyperline splits the discount across the impacted lines and creates one discount line for each allocated share. #### Rounding product When **Use Hyperline tax amounts** is off, NetSuite can recalculate invoice and credit memo totals after Hyperline sends the record. For example, NetSuite can apply its own tax or line rounding. To reconcile small differences, configure a dedicated rounding item from **Settings > Integrations > NetSuite > Tax amounts > Rounding product**. When the NetSuite total differs from the Hyperline total by one currency minor unit, such as EUR 0.01 or USD 0.01, Hyperline adds a non-taxable **Round Off** line using the selected item. The rounding item is only used for this adjustment line; regular invoice lines still use the product item mappings configured on each Hyperline product. If the difference is larger than one minor unit, Hyperline records an integration issue instead of adjusting the NetSuite record. If no rounding product is configured, Hyperline does not add a rounding adjustment line. When [Use Hyperline tax amounts](#use-hyperline-tax-amounts) is on, Hyperline keeps the rounding product mapping but does not add rounding adjustment lines. #### Bulk update product mappings During implementation, you can update NetSuite product mappings for several products from the product catalog: 1. Go to **Catalog** > **Products**. 2. Select the products you want to update. 3. Click **Bulk update**. 4. In the accounting fields, update the NetSuite item or product code mapping. 5. Click **Save**. Complete product mappings before your first invoice synchronization. Missing NetSuite item mappings stop invoice synchronization until the affected products are corrected and retried. ### Accounts Configure NetSuite account mappings from **Settings > Integrations > NetSuite > Sync rules**. Only accounts that can be used for posting are available in rules. Hyperline filters out non-posting and statistical accounts. If a NetSuite account does not appear in sync rules, check that the account is active, available to the relevant subsidiary, postable, and visible to the NetSuite role used by Hyperline. Select the rule's **Entity type** according to the account you need to configure: | Setting | Where to configure it | What it controls | | - | - | - | | Revenue account and revenue recognition rule | On the item in NetSuite; select that item on the Hyperline product | Revenue or deferred revenue on invoice, credit note, and coupon discount lines. | | **Write-off debit account** | **Invoice** sync rule | The account debited by the write-off Journal Entry for an uncollectible invoice. | | **Asset account** | **Transaction** sync rule | The bank, clearing, or Undeposited Funds account for new Customer Payments and regular Customer Refunds, including paid wallet top-ups and their refunds. | An **Invoice** sync rule does not override the revenue account of a NetSuite item. Coupon discounts use the same item as the product line they discount, so they follow that item's accounting configuration too. For example, use **Transaction** rules to send EUR bank transfers to your EUR bank account and card payments to a clearing account. Changing a rule does not move an existing Customer Payment to another account when you resynchronize it. Chargebacks use a separate account resolution path based on **Invoice settled** accounting rules. See [Account resolution details](./netsuite-advanced#accounts). #### Invoice write-offs If you synchronize invoices marked `uncollectible`, select **Invoice** as the rule's **Entity type** and configure **Write-off debit account**. Select the account appropriate to your write-off policy, such as an expense or allowance account. Hyperline creates a write-off Journal Entry for the invoice's outstanding balance, debiting that account and crediting the invoice's A/R account. A zero-amount Customer Payment applies the journal credit to the invoice. If the journal requires approval, approve it in NetSuite and retry the synchronization. If no matching rule provides a write-off debit account, synchronization stops with an issue you can fix and retry. A write-off journal and its Customer Payment application are accounting records. Marking an invoice `uncollectible` does not refund or reverse a settled payment through the payment provider. #### Accounting sync rule criteria Configure rules for the relevant invoicing entity. Use these filters to control when a mapping applies: | Entity type | Available filters | Example | | - | - | - | | **Invoice** | Currency and invoice type | Use a different write-off debit account for custom documents. | | **Transaction** | Currency, payment provider, payment method, and bank account | Send bank transfers in each currency to the corresponding bank account. | For NetSuite write-offs, product, coupon, country, tax, billing interval, and invoice custom property filters are not supported. If an existing **Invoice** rule contains unsupported filters, remove them so the rule can apply to write-offs. A rule without filters acts as a default for its invoicing entity. When multiple rules match, the highest priority wins for each mapped account role. ### Tax codes Configure tax codes at the Hyperline invoicing entity level. Hyperline resolves the tax code from the invoice tax settings and sends it to NetSuite for taxable invoice lines. See [Tax management](../docs/invoices/tax-management) for the Hyperline tax setup. ### Use Hyperline tax amounts By default, NetSuite calculates taxes from the mapped tax codes. Enable **Use Hyperline tax amounts** to send the tax amounts already calculated in Hyperline for invoices and credit notes. This avoids differences caused by NetSuite recalculating tax. Before enabling this option, confirm that: * Your NetSuite account uses **SuiteTax**. * The integration role has at least **Edit** access to **Tax Details Tab** and can edit tax details on both **Invoice** and **Credit Memo** records. See [Oracle's tax details permissions](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_4283867856.html). * Your mapped tax codes identify SuiteTax tax items with a tax type. Tax groups are not supported for this option. To enable it: 1. Open **Settings > Integrations > NetSuite**. 2. In **Tax amounts**, turn on **Use Hyperline tax amounts**. 3. Click **Save changes**. Hyperline checks whether the connected account and integration role support editing tax details on both record types before saving. If the account does not support the option, or Hyperline cannot verify access, Hyperline rejects the save with an error and does not enable the setting. Correct the reported account, permission, or connection issue, then save again. With this option enabled, Hyperline checks that NetSuite preserves the tax amounts and document total after synchronization. Any mismatch creates an integration issue instead of a rounding adjustment. Test an invoice and a credit note with the intended integration role before using this option for live synchronization. ### Payment synchronization You configure payment, refund, and chargeback synchronization per payment method, such as card, direct debit, bank transfer, external payments, and other payment sources. Each payment method can be set to: * **No synchronization**: payments, refunds, and chargebacks using this method are not sent to NetSuite. * **From Hyperline to NetSuite**: settled payments, settled refunds, and chargebacks are sent to NetSuite with their current applications. Hyperline creates one NetSuite Customer Payment for each eligible settled transaction. The payment applications follow the transaction's current allocations in Hyperline: * One transaction can be applied to one or more NetSuite invoices. * An unallocated transaction is created in NetSuite without an invoice application. * If you unallocate or reallocate an amount in Hyperline, Hyperline updates the NetSuite Customer Payment applications without deleting the payment. * Any amount that is not allocated to an invoice remains unapplied on the NetSuite Customer Payment. For example, if you allocate a €500 bank transfer as €300 to one invoice and €150 to another, the NetSuite Customer Payment keeps its full €500 amount, applies €300 and €150 to the matching invoices, and leaves €50 unapplied. Moving an unallocated amount to the customer's wallet is different from leaving it unapplied. Hyperline tracks that amount as wallet funds and updates the Customer Payment when the wallet funds are used. Invoice overpayments are not automatically added to the wallet. See [Understand payment allocations](/docs/payments/allocations) for the complete allocation model. ### Optional field mappings You can map Hyperline customer fields, invoice custom properties, and invoice line fields to NetSuite fields from **Settings > Integrations > NetSuite**. This is useful for reporting dimensions such as location, department, class, contract references, or service periods. Create the relevant [custom properties](../docs/properties/overview) in Hyperline before mapping them to NetSuite fields. ### Refresh reference lists Hyperline caches the NetSuite customer, invoice, and invoice-line fields and the tax codes used by the mapping selectors. Refresh them from **Settings > Integrations > NetSuite > Reference lists** after you add a new custom field or tax code in NetSuite that is missing from a Hyperline mapping picker. * **Refresh fields**: re-fetches the customer, invoice, and invoice-line field lists used by the [optional field mappings](#optional-field-mappings). The mapping selectors pick up the new values automatically within about two minutes. * **Refresh tax codes**: re-syncs the saved tax code mappings for every invoicing entity. Save an invoicing entity mapping first, otherwise the action has nothing to refresh. Reopen the tax code selector to see the updated list. Refreshing requires the settings-update permission and does not save any unsaved changes on the page. ## Synchronization behavior Hyperline sends eligible records to NetSuite automatically after they are created or updated. Synchronization runs asynchronously. Queue backlog, NetSuite rate limits, and retries can delay completion; five minutes is not a guaranteed maximum. By default, only data created after the connection date is synchronized. To send older data, contact our support team or use **Resync** when the option is available from the integration actions menu. ### Daily catch-up synchronization Hyperline runs an additional NetSuite catch-up synchronization every day at **05:00 UTC**. This complements the regular synchronization and helps recover records that could not be sent during an earlier attempt. The daily run processes records in this order: 1. Retry eligible customer and invoice issues from previous runs, with customer issues first. 2. Synchronize customers changed since the previous daily run. 3. Synchronize invoices changed since the previous daily run. Hyperline automatically retries transient issues, such as temporary NetSuite or network errors, once per daily run for up to three automatic attempts. Configuration and validation issues, such as a missing item or account mapping, are not retried automatically because they require a correction first. Fix these issues, then retry them from **Settings > Integrations > NetSuite > View issues**. An automatically retried issue temporarily appears as retrying. After a successful synchronization, Hyperline removes the related issue from the open issues list. If the retry fails, the issue remains open with the latest error. Hyperline prevents two daily catch-up runs from overlapping. If a manual resync and the daily run target the same customer or invoice at the same time, Hyperline deduplicates the work so the record is not synchronized twice concurrently. ### Locked accounting periods For invoices, credit notes, and customer payment creation or updates, Hyperline checks the NetSuite accounting period for the transaction date. If that period is closed, fully locked, or A/R locked, Hyperline keeps the original transaction date and sends the record to the nearest open NetSuite posting period. Customer Payment deletion is stricter. If the NetSuite Customer Payment belongs to a closed, fully locked, or A/R locked period, Hyperline does not delete it and records an integration issue. An administrator can adjust or remove the payment in NetSuite, then resolve or ignore the issue in Hyperline when the accounting state is correct. For creation and updates, you do not need to reopen the locked period or change the financial date in Hyperline. The following invoice statuses are not pushed to NetSuite: * **draft** * **open** * **charged on parent** * **pending parent concatenation** * **closed** * **archived** ## Refunds, chargebacks, and wallet activity Credit notes are synchronized as NetSuite **Credit Memo** records. When a credit note is linked to an invoice in Hyperline, Hyperline applies the NetSuite Credit Memo to the matching NetSuite Invoice. Settled refunds are synchronized as NetSuite **Customer Refund** records when the payment method is configured to synchronize. Hyperline updates the original Customer Payment or Credit Memo applications to reflect the refund's current allocations. Chargebacks are also synchronized as NetSuite **Customer Refund** records applied to the original Customer Payment. Hyperline keeps the payment's remaining invoice applications aligned with the current allocations. When the chargeback is cleared or the transaction is deleted in Hyperline, Hyperline removes the related Customer Refund and restores the Customer Payment applications. When a credit note is refunded to the customer's wallet, Hyperline does not create a NetSuite Customer Refund because no cash refund is sent back to the customer. Instead, Hyperline applies the NetSuite Credit Memo to the original invoice and keeps the customer value available as wallet balance in Hyperline. If the original NetSuite invoice was already closed by payments, Hyperline first opens the invoice balance for the credit memo: * For wallet-paid invoices, Hyperline reduces or removes the wallet top-up Customer Payment application. * For card, direct debit, bank transfer, or other Hyperline-synchronized payments, Hyperline reduces the matching Customer Payment application for the credited amount. * For invoices paid by both wallet and another payment method, Hyperline adjusts the wallet payment first, then reduces the other synchronized payment only for the remaining amount. Hyperline does not change manual or unknown NetSuite payments when preparing a wallet-refunded credit note. If such a payment blocks the credit memo application, Hyperline records an integration issue so the payment can be reviewed in NetSuite. If NetSuite has locked a Customer Payment because it is deposited, Hyperline cannot change which invoices that payment is applied to. If the payment is included in a NetSuite Deposit, remove it from that Deposit. If the payment is posted directly to a bank account and shows as deposited, edit the Customer Payment and move it to Undeposited Funds. Then retry the failed synchronization from Hyperline. Hyperline will then reopen the original invoice balance and apply the Credit Memo. Paid wallet top-ups are handled separately from regular invoices: * Hyperline does not create or push an invoice, receipt, or payment advance document for a paid wallet top-up. * Paid top-ups are synchronized as NetSuite Customer Payments when eligible. * Wallet payments are applied to the NetSuite invoices paid with wallet balance, using the wallet funding allocations recorded in Hyperline. * If one transaction is partly allocated directly to an invoice and partly added to the wallet, Hyperline keeps one Customer Payment for the full transaction and preserves both types of application. * When a paid top-up is reverted, Hyperline removes the wallet-funded applications, preserves any direct applications from the same transaction, and creates a Customer Refund for the eligible reverted amount. If the original Customer Payment was not synchronized, Hyperline records an integration issue instead. * Free wallet credits are not pushed as Customer Payments. ## Guides ### Record an offline payment Select the payment action based on how the payment should be applied. #### Apply a payment to an invoice Use **Add payment** when you want to allocate an existing transaction or record a new payment received outside Hyperline. 1. Open the invoice in Hyperline. 2. Click **Actions** > **Add payment**. 3. Select **Use existing transaction** to allocate a transaction with an unallocated amount, or select **Record offline payment** to record a new bank transfer or external payment. 4. Enter the amount to apply and any requested payment details. 5. Click **Add payment**. When the payment method is configured to synchronize, Hyperline sends the settled payment to NetSuite as a **Customer Payment** applied to the matching NetSuite Invoice. To use the same transaction for another invoice, repeat these steps and select **Use existing transaction**. Hyperline adds another application to the same NetSuite Customer Payment. #### Keep payment funds for future invoices Add funds to the customer's wallet when the amount should remain available for future invoices or participate in automatic collection. 1. Open the customer in Hyperline. 2. Go to the **Wallet** tab. 3. Click **Add offline payment**. 4. Select **Use existing transaction** to move its complete unallocated amount to the wallet, or select **Record transaction** to record a new bank transfer or external payment. 5. Enter the requested payment details and confirm. When you want to use the funds: 1. Open the invoice you want to settle. 2. Click **Actions** > **Pay with wallet**. 3. Select the amount to allocate from the wallet to the invoice. 4. Repeat the wallet payment action on any other invoice that should use part of the same payment. Any unused amount remains in the customer's wallet. When the related payment method is configured to synchronize, Hyperline sends the full context to NetSuite: the Customer Payment, its direct invoice applications, the invoices paid with wallet balance, and any amount that remains unapplied. ## Monitor and recover If NetSuite rejects a record or a mapping is missing, Hyperline records an integration issue. Open **Settings > Integrations > NetSuite > View issues** to review the error, fix the configuration or source data, then retry the synchronization. Use **Resync** from the integration actions menu after changing mappings, reconnecting NetSuite, or correcting issues that affected existing records. For accounting integrations, **Resync** can send missing invoices, update existing provider invoices, and update linked customers. See [Manage connected integrations](./manage-integration) for details about reauthorization, reconfiguration, resync, and disconnection actions. ### Sync history Open **Settings > Integrations > NetSuite > View syncs** to review every synchronization run Hyperline has executed for the connection. Use this view to confirm that a resync completed, to check what a scheduled run processed, or to find the record that caused a failure. Each row in the **Syncs** view is one run, with its start date, the number of syncs it contains, its origin, and its status. Narrow the list with the available filters: | Filter | Values | | - | - | | **Date** | A start date range for the runs. | | **Entity** | Customer, Invoice, Credit note, Transaction, or Subscription. | | **Origin** | **Automatic** for runs Hyperline starts from events or schedules; **Manual** for runs a user triggers. | | **Status** | Processing, Succeeded, Failed, Skipped, or Unknown. | | **Search** | A Hyperline entity ID, to find the runs that touched a specific record. | Click a run to open its details. The overview shows the run's date, origin, trigger, status, sync count, and correlation ID. The trigger tells you what started the run: **Event**, **Scheduled**, **Resync**, **Manual sync**, or **Retry**. For manual runs, a **Triggered by** field shows the user who started the run. Below the overview, the run details list each entity-level sync with its operation (**Create or update**, **Delete**, or **Sync**) and status. Each entity is linked, so you can open the related customer, invoice, credit note, transaction, or subscription directly. Hover over a **Failed** status to see the error message, or click the sync to open its full details, including the error and correlation ID. ### Manually resync a transaction You can resend a single payment, refund, or chargeback to NetSuite without running a full resync. This is useful after fixing the configuration or NetSuite data that made the original transaction sync fail. Manual transaction synchronization requires the **invoices\_update** permission. 1. Open the transaction in Hyperline. 2. Click the integrations button, then select **Resync with NetSuite**. 3. Click **Synchronize** to confirm. Hyperline queues the synchronization and processes it within a few moments. The run appears in the sync history with the **Manual** origin and the **Manual sync** trigger, and shows you as the triggering user. Is something still unclear? Don't hesitate to reach out to our team via the in-app chat if you need additional support. ## Next steps * Review sync rules on **Settings > Integrations > NetSuite** before mapping NetSuite accounts. * Configure [tax settings](../docs/invoices/tax-management) for each invoicing entity. # Outlook Source: https://docs.hyperline.co/integrations/outlook Connect Outlook per user to bring recent customer email threads into Hyperline, so the customer monitoring agent can weigh relationship signals. [Outlook](https://outlook.com) is Microsoft's email service. Connecting it lets Hyperline read the email threads you exchanged with your customers. The customer monitoring agent can then weigh how a relationship is going alongside contract, invoice, payment, and usage data. Outlook is part of [Customer intelligence](../docs/customer-intelligence/overview), a paid add-on. Contact the Hyperline team through the in-app chat to enable it. Outlook is **user-scoped**: each teammate connects their own mailbox from **Profile > Integrations**, not from the workspace-level **Settings > Integrations** page. Hyperline only sees the mailboxes of the users who connected. ## Prerequisites A Microsoft account with the mailbox you want Hyperline to read. ## Connect Outlook You are redirected back to Hyperline and the connection appears as active for your user. ### Requested permissions | Permission | Why it is needed | | - | - | | Read your mail | Retrieve the messages exchanged with your customer domains | | Read your profile | Identify which account is connected | | Maintain access | Keep the connection working without asking you to sign in again every hour | The connection is read-only. Hyperline never sends, replies to, deletes, or modifies anything in your mailbox. ## What Hyperline fetches Hyperline never reads your whole mailbox. It searches Outlook once per customer domain, for messages sent to and received from that domain, then keeps only the results that match a known customer. For every matched email, Hyperline stores: | Data | Details | | - | - | | Conversation | The conversation identifier, so messages stay grouped by thread | | Subject | The subject line | | Participants | Sender name and address, recipients, and copied addresses | | Body | The message content | | Date | When the message was received | Hyperline always skips the following and never stores them: * Drafts * Anything in **Junk Email** or **Deleted Items**, including their subfolders * Messages with no received date * Messages whose correspondent does not match a customer domain Keep customer **Domain** values up to date. The domain is what decides which searches run and which messages are kept. ## Synchronization Hyperline synchronizes mailboxes once a day, for every user who connected their Microsoft account. The recurring run looks one day back, so it only picks up new messages. A full-history search runs instead when the sync is scoped to a single domain, for example when a customer is created. That search is capped per domain, so a very large history is not retrieved in full. ## Where Outlook data appears * **Customer page**: the **Integrations** section shows an Outlook row with the most recent email. Open it to browse synced threads and their content. * **Monitoring agent**: email is handled separately from the other connectors. When Outlook is connected for users in your workspace, the agent can use recent customer email threads without a toggle in the agent's **Connectors** tab. * **Analysis results**: Outlook appears under **Data sources** when email context was used. ## Manage the connection Open **Profile > Integrations** to review or remove your own connection. Disconnecting stops Hyperline from reading your mailbox. Each teammate manages their own connection, so removing yours does not affect anyone else's. ## Related * [Gmail](./gmail) * [Customer intelligence](../docs/customer-intelligence/overview) * [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent) * [Integrations overview](./overview) # Integrations overview Source: https://docs.hyperline.co/integrations/overview Browse Hyperline integrations for payment gateways, accounting systems, CRMs, tax engines, and automation platforms to connect your billing stack. ## Payment gateway } href="./stripe" > Use Stripe's global payment processing platform as a payment gateway. } href="./mollie" > Use Europe-based Mollie payment processor as payment gateway. } href="./gocardless" > Use GoCardless direct debit as payment gateway. } href="./airwallex"> Use Airwallex payment processor as payment gateway. } href="./adyen" > Use Adyen payment platform as payment gateway. ## CRM } href="./salesforce" > Bi-directionally sync your Hyperline data with your Salesforce instance, and fully manage your quotes and subscriptions directly from your CRM. } href="./hubspot" > Bi-directionally sync your Hyperline data with your HubSpot account, and fully manage your quotes and subscriptions directly from your CRM. } href="./attio" > Bi-directionally sync your Hyperline data with your Attio account, and fully manage your quotes and subscriptions directly from your CRM. ## Accounting software } href="./pennylane" > Push your Hyperline invoicing data and reconcile easily with Pennylane. } href="./xero" > Push your Hyperline invoicing data and reconcile easily with Xero. } href="./quickbooks" > Push your Hyperline invoicing data and reconcile easily with QuickBooks. } href="./netsuite" > Push your Hyperline invoicing data and reconcile easily with NetSuite. } href="./rillet" > Push your Hyperline invoicing data and reconcile easily with Rillet. } href="./campfire" > Push your Hyperline invoicing data and reconcile easily with Campfire. } href="./exact-online" > Push your Hyperline invoicing data and reconcile easily with Exact Online. } href="./zoho-books" > Push your Hyperline invoicing data and reconcile easily with Zoho Books. } href="./datev" > Push your Hyperline invoicing data to DATEV. ## Tax engine } > Compute taxes with Hyperline, only available in the EU. } > Connect and use your Anrok account as tax engine on Hyperline. } > Connect and use your Sphere account as tax engine on Hyperline. ## Signature } > Native and embedded electronic signature flow. } > Connect and use your DocuSign account as signature provider on Hyperline. } > Connect and use your Yousign account as signature provider on Hyperline. ## AI } href="https://chatgpt.com/apps/hyperline/asdk_app_6a1da415f0908191b74b5b89f9546b4f" > Access Hyperline from ChatGPT to answer questions and manage revenue operations. } href="../api-reference/docs/ai/mcp" > Connect Claude to Hyperline through MCP. } href="../api-reference/docs/ai/mcp" > Connect Cursor to Hyperline through MCP. ## Support platform } href="./intercom" > Bring Intercom support conversations into customer intelligence. } href="./front" > Bring Front support conversations into customer intelligence. } href="../docs/customer-intelligence/overview" > Bring Plain support conversations into customer intelligence. } href="./pylon" > Bring Pylon support conversations into customer intelligence. } href="./help-scout" > Bring Help Scout support conversations into customer intelligence. } href="./zendesk" > Bring Zendesk support conversations into customer intelligence. ## Email } href="./gmail" > Use Gmail messages as context in customer intelligence. } href="./outlook" > Use Outlook messages as context in customer intelligence. ## Call recording } href="./google-meet" > Use Google Meet call recordings and Gemini meeting notes in customer intelligence. } href="./claap" > Use Claap call recordings and meeting notes in customer intelligence. } href="../docs/customer-intelligence/overview" > Use Attio call recordings and meeting notes in customer intelligence. } href="./grain" > Use Grain call recordings and meeting notes in customer intelligence. } href="./granola" > Use Granola meeting notes, summaries, and transcripts in customer intelligence. } href="./gong" > Use Gong call recordings, summaries, and transcripts in customer intelligence. } href="./jiminny" > Use Jiminny call recordings, summaries, and transcripts in customer intelligence. } href="./modjo" > Use Modjo call recordings, summaries, and transcripts in customer intelligence. ## Usage data } href="../docs/usage/usage-data-with-connectors" > Automatically pull usage data from your MySQL database. } href="../docs/usage/usage-data-with-connectors" > Automatically pull usage data from your PostgreSQL database. } href="../docs/usage/mongodb" > Automatically pull usage data from your MongoDB database. } href="../docs/usage/bigquery" > Automatically pull usage data from your BigQuery database. } href="../docs/usage/snowflake" > Automatically pull usage data from your Snowflake database. } href="../docs/usage/posthog" > Automatically pull usage data from your PostHog project. } href="./segment" > Push events collected by Segment to Hyperline. } href="./hightouch" > Sync data from databases, warehouses, spreadsheets, and more to Hyperline. ## Automation } href="./zapier" > Create any custom workflow with no-code using the native Hyperline Zapier app. } href="./slack" > Send messages to Slack in reaction to events in Hyperline. ## Analytics } href="../docs/analytics/insights" > Explore financial and revenue metrics with interactive charts, drill-down tables, and custom filters. } href="https://www.fincome.co?utm_source=hyperline"> Monitor and analyze Hyperline subscription revenue with Fincome. } href="https://www.chartmogul.com?utm_source=hyperline" > Monitor and analyze Hyperline subscription revenue with ChartMogul. # Pennylane Source: https://docs.hyperline.co/integrations/pennylane Push invoices, credit notes, and customer data from Hyperline to Pennylane accounting for French SMBs with automatic ledger synchronization. [Pennylane](https://www.pennylane.com) is a French financial and accounting management solution, available as SaaS. ## Prerequisites You need to have a valid [Pennylane account](https://www.pennylane.com) and admin rights on Hyperline. ## Setup If you are not already logged into Pennylane, enter your Pennylane credentials to proceed. Select and authorize the company you want to use. Your Hyperline account is ready to send invoices and credit notes. ## Reconcile Hyperline and Pennylane customers If you already have customers in Pennylane, link them with the corresponding customers in Hyperline. Open **Settings > Integrations > Pennylane** and click **Import customers mapping** under **Customers mapping** to contact support for help with the import. ## Synchronization When you connect your Pennylane account, Hyperline **automatically sends invoices** with their complete details (including line items and PDF file). Hyperline only exports invoices created in Hyperline to Pennylane. Invoices imported from Pennylane into Hyperline (or linked to Hyperline-managed subscriptions) are not re-exported to avoid duplication and data conflicts. If you use Stripe Payments or GoCardless with Hyperline, you also must connect them directly to your Pennylane account to ensure proper enrichment and reconciliation flow in Pennylane. By default, only invoices and customers created after the connection date will sync. If you need to push older data to Pennylane, please contact our support team. ### Customer synchronization Hyperline supports 2 modes of synchronization for customers: * **no synchronization**: customers are not synchronized with Pennylane. * **from Hyperline to Pennylane**: customers created in Hyperline are automatically created in Pennylane with their details. Alternatively, you can manually link a Pennylane customer to a Hyperline customer. On the Hyperline customer page, click the `Edit` button in the `Integrations` section, then paste either the Pennylane customer ID or the URL to the Pennylane customer page. ### Payment synchronization Hyperline supports 3 modes of synchronization for payments: * **no synchronization**: payments are not synchronized with Pennylane. * **from Hyperline to Pennylane**: Hyperline automatically creates payments in Pennylane and associates them with the corresponding invoice. Due to a Pennylane API limitation, only payments done using Stripe or GoCardless can be synced. * **from Pennylane to Hyperline**: payments created in Pennylane are automatically created in Hyperline, and the status of the invoice is updated accordingly. The synchronization delay is 5 minutes maximum. ## Map invoice properties to analytical categories Use **Mapping > Invoice** to send invoice [custom properties](/docs/properties/overview) from Hyperline to Pennylane analytical categories. Each property maps to a Pennylane category group, and each property value maps to a category within that group. Before configuring a mapping, create a **text** or **single-select** custom property available on invoices in Hyperline, and create the category group and categories in Pennylane. Other property types are not supported. 1. Open **Settings > Integrations > Pennylane**. 2. Under **Mapping > Invoice**, click **Add mapping**. 3. Select the invoice property under **Hyperline field** and the analytical group under **Pennylane field**. Use a different property and group for each mapping. 4. Click **Configure value mapping** below the Pennylane selector. 5. Click **Add value mapping**, enter or select a **Property value**, and select its **Category**. For text properties, values must match exactly, including capitalization. Add a row for each value your invoices use. 6. Click **Done**. At least one complete row is required. Each property value can appear only once within the mapping. 7. Enable **Required** if an invoice must have a value for this property to sync. 8. Click **Save changes** on the integration settings page to save the configuration. **Done** only confirms the modal's entries. Map the Hyperline invoice property **Region** to the Pennylane group **Sales region**, then map `EU` to **Europe**. An invoice with `EU` receives a 100% allocation to **Europe** within that group. ### How category mappings sync * Each matching value assigns 100% to one category in its group. Splitting an allocation across several categories in the same group is not supported. * For a mapped group with a matching value, Hyperline replaces the existing allocation. Allocations in other groups remain unchanged. * An empty optional property leaves the group's existing allocation unchanged. An empty required property blocks synchronization. * A non-empty value without a matching category mapping blocks synchronization, even when **Required** is off. Add the missing value mapping, then retry. * Changing the selected Hyperline property or Pennylane group clears its value mappings. Configure them again before saving. To apply changes to invoices already in Pennylane, use [**Resync**](/integrations/manage-integration#resync-accounting-data) after saving the settings. If Hyperline asks you to reconnect to load analytical categories, use **Reauthorize** in the integration's actions menu and grant access in Pennylane. Existing connections may need this additional authorization before category groups can load. ## Synchronization rules Synchronization rules select the Pennylane revenue account for each invoice or credit note line. Use them when different products or tax treatments need different accounts. 1. Open **Settings > Integrations > Pennylane**. In **Synchronisation rules**, open the rule count card or **No rules configured**, then click **Add rule**. 2. Select the **Invoicing entity** if prompted and enter a descriptive **Name**. 3. Under **Applied on**, add filters for the lines the rule should cover. You can filter by products, product type, coupons, currency, country, tax scheme, tax territory, tax rate class, billing interval, invoice types, or custom properties. 4. Under **Account configuration**, select a **Revenue account**. Use **Sync accounts from Pennylane** to refresh the available accounts. 5. Click **Save changes**. A matching rule's account takes precedence over the product account code. The selected account must exist in Pennylane's chart of accounts; otherwise, synchronization fails with a missing-account error. See [Product and account codes](#product-and-account-codes) for Pennylane's account-code format. Leave filters empty to create a default rule. At the same priority, a rule scoped to a matching product takes precedence over the default. Avoid overlapping rules with conflicting accounts. Select your software subscription revenue account in a default rule, then add a rule filtered to your onboarding product with a separate services revenue account. Pennylane receives each line with the corresponding account. Pennylane synchronization rules apply to invoice and credit note accounts. They do not select payment accounts or journals, or change your customer and payment synchronization modes. ## Manage the integration To reauthorize, reconfigure, resync, or disconnect this integration, see [Manage connected integrations](/integrations/manage-integration). ### Product and account codes Configure account codes on products in Hyperline **without trailing zeros**. For example, if your Pennylane account code is `7010301000`, you should enter `7010301` in Hyperline. Pennylane may display account codes with trailing zeros, but you should remove them when configuring the codes in Hyperline to ensure proper synchronization. ## Troubleshooting sync errors If a Pennylane sync fails, open the Pennylane integration issues page in Hyperline to review the latest error. Retry after you correct the data. Common causes include: | Error | What to check | | - | - | | Duplicate payment | The payment may already exist in Pennylane, often because it was created manually or synced from the payment provider. Remove the duplicate or adjust the reconciliation in Pennylane before retrying. | | Line total or VAT mismatch | Pennylane rejected the invoice because the line totals, tax rates, or VAT amounts do not match its expected calculation. Check the invoice lines, tax codes, and rounding before retrying. | | Missing property value or category mapping | Fill the required invoice property or add its value under **Configure value mapping**, click **Save changes**, then retry. Confirm the selected category still exists in Pennylane. | | Missing customer or account code | The linked customer, product account code, or ledger mapping is missing or invalid. Complete the mapping in Hyperline, then retry the sync. | By default, only invoices, customers, and payments created after the Pennylane connection date are synchronized. If you need to push older data, contact support to request a backfill. During some migrations, Pennylane can display an imported invoice as partially paid even when the invoice total is fully covered by payments. This usually comes from a header-total or reconciliation mismatch. Contact support with the invoice ID so the team can review the Pennylane response. # Pylon Source: https://docs.hyperline.co/integrations/pylon Connect Pylon with Hyperline to attach support issues, tags, statuses, and messages to customers and surface support pressure to the agent. [Pylon](https://usepylon.com) is a B2B support platform that centralizes customer conversations from shared Slack channels, email, and other channels. Connecting Pylon lets Hyperline attach support issues to the matching Hyperline customers. The customer monitoring agent can then weigh unresolved issues and support pressure alongside contract, invoice, payment, and usage data. Pylon is part of [Customer intelligence](../docs/customer-intelligence/overview), a paid add-on. The Pylon card only appears in **Settings > Integrations** when Customer intelligence is enabled for your account. Contact the Hyperline team through the in-app chat to enable it. ## Prerequisites * A valid [Pylon account](https://usepylon.com). * A Pylon API token, created by a Pylon administrator from your Pylon settings. * Admin rights on your Hyperline account. ## Connect Pylon Hyperline validates the token immediately and rejects it if it is invalid or revoked. The integration appears as connected and Hyperline starts matching your Pylon accounts to Hyperline customers. The connection is read-only. Hyperline only reads accounts, issues, and messages, and never writes to Pylon. ## What Hyperline fetches For every matched issue, Hyperline stores: | Data | Details | | - | - | | Issue | Pylon issue identifier, title, and a short preview of the body | | Status | Normalized to `open`, `closed`, or `snoozed` | | Tags | The issue tags, used as labels | | Requester | Email of the person who opened the issue | | Dates | Creation date, last update date, and the date of the most recent message | | Messages | Each message with its body, author name, whether it came from the customer or an agent, and its date | Pylon does not expose issue priority levels, so every synced issue carries the same default priority in Hyperline. Private messages are synced alongside public ones and stored as notes. Anything written on an issue in Pylon can therefore be used as context by the monitoring agent. ### Which issues are matched Hyperline first resolves the Pylon **account** that corresponds to a Hyperline customer, by comparing the customer **Domain** against the account's domains in Pylon. Once an account is matched, the link is stored and later syncs query issues directly by account. Hyperline skips public email domains, such as `gmail.com`: an account lookup on them would match unrelated issues. Keep customer **Domain** values up to date. The domain is the only signal used to find the matching Pylon account the first time. ## Synchronization Hyperline synchronizes Pylon once a day, and also refreshes a customer on demand when the customer monitoring agent analyzes it. Synchronization is incremental: an issue whose most recent message has not changed since the last run does not have its messages fetched again. ## Where Pylon data appears * **Customer page**: the **Integrations** section shows a Pylon row with the most recent thread. Open it to browse synced issues with their statuses, labels, and messages. * **Monitoring agent**: enable Pylon from the agent's **Connectors** tab. See [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent). * **Analysis results**: Pylon appears under **Data sources** when support context was used. ## Manage the integration Open **Settings > Integrations** and select **Pylon**. Synchronization errors, such as a revoked token, are reported on this page. Use **Disconnect** to stop synchronizing new issues. Revoke the API token in Pylon as well if you want to invalidate it entirely. ## Related * [Customer intelligence](../docs/customer-intelligence/overview) * [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent) * [Integrations overview](./overview) # QuickBooks Source: https://docs.hyperline.co/integrations/quickbooks Push invoices, credit notes, customers, and payments from Hyperline to QuickBooks Online accounting with chart of accounts and tax mapping. [QuickBooks](https://www.quickbooks.com) is a US accounting software developed by Intuit. ## Prerequisites You need to have a valid [QuickBooks account](https://www.quickbooks.com) and admin rights on Hyperline. ## Setup If you are not already logged into QuickBooks, enter your QuickBooks credentials to proceed. Your Hyperline account is ready to send invoices and credit notes. ## Reconciling data ### Customers To link an existing QuickBooks customer to a Hyperline customer, navigate to the customer details page, click the "Edit" button in the "Integrations" section, and enter the QuickBooks customer ID. For bulk operations during initial setup, contact our support team or use [this API endpoint](../api-reference/endpoints/customers/bulk-update-providerscustomers-mapping.mdx). ### Products You can map your QuickBooks products (items) to your Hyperline product catalog. For each product in Hyperline, go to the Accounting section and enter the corresponding QuickBooks item name in the "Product code" field. When specified, Hyperline automatically attaches each invoice line item to the corresponding item in QuickBooks. ### Taxes When pushing an invoice with taxable line items, QuickBooks requires a tax code to be associated with each line. You can provide it in two ways: * **At the product level**: Define a specific tax code on each product in Hyperline (Catalog → Products → Accounting → Tax code). This code is used when the product appears on an invoice. * **At the invoicing entity level**: Configure tax codes on the default tax rates of the invoicing entity, in **Settings > Invoicing entities > Taxes**. Hyperline resolves the right tax code based on the invoice's tax rate before pushing it to QuickBooks. See [Default tax rates](../docs/invoices/tax-management#tax-mappings) for details. As a fallback, you can set a **Default tax code** in **Settings > Integrations > QuickBooks**. It is used whenever a taxable line item has no resolved tax code. For US QuickBooks accounts, only the built-in `TAX` and `NON` tax codes are supported on line items. The Default tax code is still required to push invoices with non-zero tax, as QuickBooks uses it to override the computed sales tax. ## Synchronization When you connect your QuickBooks account, Hyperline **automatically sends invoices** with their complete details (including line item details). By default, only invoices and customers created after the connection date will sync. If you need to push older data to QuickBooks, please contact our support team. ### Customers Hyperline supports 2 modes of synchronization for customers: * **no synchronization**: customers are not synchronized with QuickBooks. * **from Hyperline to QuickBooks**: customers created in Hyperline are automatically created in QuickBooks with their details. ### Payments Hyperline supports 3 modes of synchronization for payments: * **no synchronization**: payments are not synchronized with QuickBooks. * **from Hyperline to QuickBooks**: payments created in Hyperline are automatically created in QuickBooks and associated to the corresponding invoice. * **from QuickBooks to Hyperline**: payments created in QuickBooks are automatically created in Hyperline, and the status of the invoice is updated accordingly. Synchronization occurs within 5 minutes. ## Synchronization rules You can open the shared rule form from **Settings > Integrations > QuickBooks > Synchronisation rules**. QuickBooks uses item-based revenue accounting, so a **Revenue account** selected in this form does not override the income account on an invoice or credit note line. Configure the account through the mapped QuickBooks item: 1. In QuickBooks, check the income account assigned to the item you want to invoice. 2. In Hyperline, open the product's **Accounting** section and enter the matching QuickBooks item name in **Product code**. 3. Synchronize an invoice and check that the item and income account are correct in QuickBooks. To separate subscription and implementation revenue, use two QuickBooks items with different income accounts and map each Hyperline product to the corresponding item. Transaction and journal rules are not available for QuickBooks. Keep using the [payment synchronization settings](#payments) to control payment direction and the [tax mappings](#taxes) to configure tax codes. ## Manage the integration To reauthorize, reconfigure, resync, or disconnect this integration, see [Manage connected integrations](./manage-integration). ## Troubleshooting If you encounter any issues with the integration (missing data, failed entity synchronization, etc.), we recommend checking the Hyperline issues page for more details: Settings > Integrations > QuickBooks > View issues. ### Common issues **Invoice has taxable line items but no product tax code defined and no default tax code ref provided** Hyperline raises this error when it tries to push an invoice with taxable line items but cannot resolve a tax code for at least one line. This only happens when no Default tax code is configured on the integration. To fix it, set a tax code on the affected product(s), set tax codes on the default tax rates in **Settings > Invoicing entities > Taxes**, or set a **Default tax code** in **Settings > Integrations > QuickBooks**. See the [Taxes](#taxes) section for details. # Rillet Source: https://docs.hyperline.co/integrations/rillet Push invoices, credit notes, customers, payments, and subscription contracts from Hyperline to Rillet accounting with per-entity subsidiary mapping. [Rillet](https://www.rillet.com) is a modern AI-native ERP and accounting platform built for software companies. ## Prerequisites You need to have a valid [Rillet account](https://www.rillet.com), an API key issued from Rillet, and admin rights on Hyperline. ## Setup Hyperline uses the API key to authenticate every call to your Rillet account. You can revoke the key from Rillet at any time. On the **Settings > Integrations > Rillet** page, link each Hyperline invoicing entity to a Rillet subsidiary. The subsidiary drives the currency, accounts and tax codes available in the rest of the configuration. Select **Revenue recognition only** or **Full accounting sync**, configure your products and (optionally) enable subscription contract sync. See [Settings](#settings) and [Mapping](#mapping) below. Your Hyperline account is ready to send invoices, credit notes, payments and contracts to Rillet. ## Settings You can configure the following options on the **Settings > Integrations > Rillet** page: * **Invoicing entity mapping**: per-entity table linking each Hyperline invoicing entity to a Rillet subsidiary. You must map a subsidiary for each entity that issues invoices. Invoice push fails for any entity without a mapping. * **Revenue recognition mode**: see [Revenue recognition mode](#revenue-recognition-mode) below. * **Bank account**: cash account used to post payments in Rillet. Required when **Full accounting sync** is selected. The list is pulled from your Rillet chart of accounts. * **Sync subscriptions as contracts**: when enabled, Hyperline pushes each subscription to Rillet as a contract so Rillet can schedule revenue automatically. See [Contract sync](#contract-sync). ### Revenue recognition mode Hyperline can push invoices to Rillet in two different ways: * **Revenue recognition only** (default): Hyperline sends invoices so Rillet can recognize revenue. Rillet automatically settles payments on its side, so payments are not pushed from Hyperline. * **Full accounting sync**: Hyperline sends invoices and the matching payments to Rillet, including accounts receivable tracking. Requires a bank account to be configured. The mode applies to both invoices and credit notes. ## Mapping ### Customers To link an existing Rillet customer to a Hyperline customer, open the Hyperline customer page, click **Edit** in the **Integrations** section, and paste the Rillet customer ID. For bulk linking during initial onboarding, contact our support team or use [this API endpoint](../api-reference/endpoints/customers/bulk-update-providerscustomers-mapping.mdx). If a Hyperline customer is not linked to any Rillet customer, the behavior depends on the **Customer sync mode** configured in Settings: * **no synchronization**: you must link the customer manually before any invoice can be pushed; otherwise the invoice push fails. * **from Hyperline to Rillet**: the customer is automatically created in Rillet the first time it is needed (typically on the first invoice push). ### Products You must map every invoice line item to a Rillet product. For each product in Hyperline, go to the **Accounting** section of the product page and enter the corresponding Rillet product identifier in the **Product code** field. If a line item is missing a product mapping, the invoice push fails with a clear error listing the affected products so you can fix the mapping and retry. ### Tax codes Tax codes are configured **at the invoicing entity level**. Set up tax codes with automatic computation in the tax settings of the relevant invoicing entity. Tax codes are then resolved according to what is configured in Hyperline and pushed to Rillet on each invoice line. ## Synchronization When you connect your Rillet account, Hyperline **automatically sends invoices, credit notes, customers, payments and (optionally) contracts** with their complete details. By default, only data created after the connection date is synced. To push older data, please contact our support team. Synchronization is **one-way: Hyperline → Rillet**. Rillet is queried read-only to fetch metadata (subsidiaries and chart of accounts). ### Customer synchronization Hyperline supports 2 modes of synchronization for customers: * **no synchronization**: customers are not automatically created. You must link them manually before any invoice can be pushed. * **from Hyperline to Rillet**: customers created in Hyperline are automatically created in Rillet with their details. ### Invoice and credit note synchronization Invoices and credit notes are pushed as native Rillet **invoices** and **credit memos**. Updates made to an invoice in Hyperline are propagated to the matching Rillet record automatically. ### Payment synchronization In **Revenue recognition only** mode, payments are not pushed to Rillet. Rillet automatically marks invoices as settled on its side once they are recognized. In **Full accounting sync** mode, Hyperline supports a **per-payment-method sync setting** (card, SEPA / ACH / BACS direct debit, bank transfer, Apple Pay, Google Pay, Stripe Link, external, other). Each can be set independently to: * **no synchronization**: payments are not synchronized. * **from Hyperline to Rillet**: payments settled in Hyperline are pushed to Rillet against the corresponding invoice using the configured bank account. The synchronization delay is 5 minutes maximum. ### Contract sync When **Sync subscriptions as contracts** is enabled, Hyperline pushes each Hyperline subscription to Rillet as a contract. Rillet uses the contract to schedule revenue recognition automatically over the subscription term. Contracts are kept in sync as the subscription evolves: changes are pushed as updates, and when a subscription is cancelled the matching Rillet contract is ended on the cancellation date. ## Synchronization rules You can open the shared rule form from **Settings > Integrations > Rillet > Synchronisation rules**. Rillet invoice and credit memo lines use the mapped Rillet product. A **Revenue account** selected in this form does not override that product's revenue account. Configure revenue accounts through your Rillet products: 1. In Rillet, check the revenue account assigned to each product you want to invoice. 2. In Hyperline, open the product's **Accounting** section and enter its Rillet product identifier in **Product code**. 3. Check that the invoicing entity is mapped to the correct Rillet subsidiary, then synchronize an invoice and review its product mappings in Rillet. To separate subscription and onboarding revenue, configure two Rillet products with the appropriate revenue accounts and map each Hyperline product to its corresponding Rillet product. Transaction and journal rules are not available for Rillet. In **Full accounting sync** mode, payments use the integration's **Bank account** setting. In **Revenue recognition only** mode, Hyperline does not send payments. See [Revenue recognition mode](#revenue-recognition-mode). ## Manage the integration To reauthorize, reconfigure, resync, or disconnect this integration, see [Manage connected integrations](./manage-integration). # Salesforce Source: https://docs.hyperline.co/integrations/salesforce Connect Salesforce with Hyperline to sync accounts, opportunities, contracts, and subscription data between your CRM and billing platform. The Hyperline-Salesforce integration connects your Salesforce instance with Hyperline. With this integration, you can access a dedicated widget directly from Salesforce to create and manage Hyperline quotes, subscriptions, and customers without leaving your CRM. This feature embeds the full Hyperline interface inside Salesforce. In addition, the integration enables optional and automatic data synchronization between Hyperline entities (such as quotes, subscriptions, and invoice details) and Salesforce's custom objects. You always have up-to-date information, and you can use this data for internal automations, workflows, and reporting within Salesforce. ## Prerequisites You must have a valid [Salesforce account](https://salesforce.com) and access to the settings of your Hyperline account. Use a **Salesforce Developer Account** to test the integration before going live. You can create a free [Salesforce Developer instance](https://developer.salesforce.com/signup) and use the [test mode](../docs/getting-started/sandbox) of your Hyperline account during setup and testing. ### Permissions Hyperline automatically sets up the required technical components in your Salesforce instance upon connection to enable notifications and real-time synchronization. For this reason, connect your Salesforce instance with a user that has the **System Administrator** profile. Otherwise, you must manually grant that user specific permissions. The user must have the following permissions: * **API Enabled**: Allows the user to execute API calls. * **Author Apex**: Allows the user to create and edit Apex classes and triggers. * **Customize Application** or **Modify All Data**: Allows the user to create or edit remote site settings. To update these permissions: 1. Click the **Gear** icon (top-right corner) and select **Setup**. 2. In the **Quick Find** box, type “Profiles” and select **Profiles**. 3. Click **Edit** next to the profile you want to update. 4. Enable the required permission checkboxes and click **Save**. ## Embedded Hyperline UIs in Salesforce ### Installation Upon connecting your Salesforce instance to Hyperline, Hyperline automatically installs a Hyperline Salesforce package. This package includes a **native Salesforce component** that you can **add to your page layouts**. Your revenue teams can keep using Salesforce while accessing all Hyperline functionalities. To add the component to an Account or Opportunity page: 1. Open any Account or Opportunity page. 2. Click the menu in the top-right corner and select **Edit Page**. 3. Search for the **Hyperline** component and drag and drop it into the page layout. 4. Click **Save**. If this is your first time editing this layout, Salesforce prompts you to **Activate** the updated view. ### Component Once installed, you can use this component on both **Account** and **Opportunity** pages. You can: * Create Hyperline quotes. * Create Hyperline subscriptions. * Manage the related Hyperline customer. Each action opens a dedicated Hyperline interface embedded directly within Salesforce. You get the full Hyperline experience without leaving your CRM. ### Settings You can fine-tune the component's behavior from **Settings** > **Integrations** > **Salesforce**. #### Root object Controls which Salesforce object the component treats as the source of truth when displaying Hyperline billing data (quotes and subscriptions). Two modes are available: * **Account**: All quotes and subscriptions of an account are displayed on both the account component and the components of its related opportunities. Select this option if your revenue team thinks about billing at the customer level and wants the full billing picture available from any opportunity tied to that customer. * **Opportunity**: Only the quotes and subscriptions attached to a specific opportunity are displayed on that opportunity's component. The account component still shows all of the account's quotes and subscriptions. Select this option if you want each opportunity to surface only its own billing items, with no cross-opportunity bleed. This setting only affects what's displayed in the embedded component. It does not change how data is synchronized with Salesforce custom objects. #### Allow creating new customer When enabled, a Salesforce user can trigger an action from an account or opportunity that isn't yet linked to a Hyperline customer. The user can then create the corresponding Hyperline customer on the fly and proceed with the action. When disabled, actions are blocked until a matching Hyperline customer exists and is linked to the Salesforce record. #### Display customers' children's data When enabled, the component also displays quotes and subscriptions belonging to the customer's children (in Hyperline's parent–child customer hierarchy), in addition to the customer's own. This is useful when you bill parent accounts but want visibility into activity across their subsidiaries from the parent's Salesforce record. ### User access You control how Salesforce users get access to Hyperline with the **Automatically register users** toggle in the **User access** section of **Settings** > **Integrations** > **Salesforce**. * **Enabled**: Salesforce users do not need an existing Hyperline account. When a user triggers a Hyperline action for the first time, Hyperline automatically creates a corresponding Hyperline user with their Salesforce email address. Hyperline assigns this user to your default Hyperline role (the ['Account manager' role](../docs/account/users-permissions#default-role) if not changed). * **Disabled**: Hyperline does not create users from Salesforce activity. Only Salesforce users who are already members of your Hyperline workspace can access Hyperline interfaces in Salesforce. [Invite users](../docs/account/users-permissions#invite-members) before they use the integration. If email matching domains are configured for your account, the **User access** section lists them. Hyperline matches a Salesforce user to an existing Hyperline user with the same email name (the part before the `@`) on any of these domains. For example, with `acme.com` and `acme.io` configured, `jane@acme.io` in Salesforce matches the existing Hyperline user `jane@acme.com`. These domains are read-only in the settings. Contact support to change them. When Hyperline interfaces open inside Salesforce, Hyperline applies the user's Hyperline role to ensure the correct view and edit permissions. You manage these permissions directly in Hyperline under **Settings** > **Team**. ### Data reconciliation When retrieving Hyperline customer data from a Salesforce account or opportunity record, Hyperline applies the following lookup mechanism: 1. If it's an opportunity record, Hyperline uses the associated account record for the lookup. 2. If the account record is already linked to a Hyperline customer through the **Integrations** section of the customer page, Hyperline uses that customer. 3. If the account record has a value in the Hyperline customer ID custom field, Hyperline looks for the corresponding customer. 4. If the account record has a value in the Hyperline external ID custom field, Hyperline looks for a customer whose ID or external ID matches that value, or whose linked Stripe customer ID matches that value (for example, a customer imported from Stripe). If the Salesforce account and the Hyperline customer were not previously linked, Hyperline automatically creates the link. This requires the integration settings to allow it: customer sync enabled, sync direction including Salesforce → Hyperline, and the account flagged for sync. If Hyperline finds a customer but the settings do not allow automatic linking, Hyperline surfaces the suggested customer in Salesforce, along with an action to manually trigger the link. If Hyperline finds no customer but the **Allow creating new customer** setting is enabled, the Salesforce user can create a new related Hyperline customer and proceed with the desired action. ## Data synchronization In addition to the fully built-in embedded UIs, the integration can also synchronize data from Hyperline to Salesforce custom objects. This synchronization is optional, and you can configure it afterward. When you connect your Salesforce workspace, you select which entities to synchronize in the Hyperline settings. Hyperline then automatically creates the required custom objects and their associated fields in Salesforce if they do not already exist. It also sets up the synchronization mechanisms. Deleting or manually modifying Hyperline custom objects and custom fields in Salesforce may break the integration and lead to unexpected behavior. Changing the data you select to synchronize requires reconfiguring the integration. This process may take a few minutes to complete. ### Prerequisites To synchronize data, Hyperline requires specific custom objects to exist in your Salesforce instance. Hyperline does not have permission to automatically create custom objects in your Salesforce instance. You must create them manually using the object names listed below. If a required custom object does not exist, you can't activate synchronization for that entity. Hyperline does not push any data to Salesforce for it. | Entity | Salesforce object name | | - | - | | Quote | `HyperlineQuote` | | Quote line item | `HyperlineQuoteLineItem` | | Quote coupon | `HyperlineQuoteCoupon` | | Quote phase | `HyperlineQuotePhase` | | Quote file | `HyperlineQuoteFile` | | Subscription | `HyperlineSubscription` | | Subscription product | `HyperlineSubscriptionProduct` | | Subscription coupon | `HyperlineSubscriptionCoupon` | | Subscription phase | `HyperlineSubscriptionPhase` | | Invoice | `HyperlineInvoice` | | Invoice line item | `HyperlineInvoiceLineItem` | | Custom property value | `HyperlineCustomPropertyValue` | To create the required custom objects: 1. Click the **Gear** icon (top-right corner) and select **Setup**. 2. In the **Quick Find** box, type “Object Manager” and select **Object Manager**. 3. Click the **Create** dropdown and select **Custom Object**. 4. Fill in the **Label**, **Object Name**, and **Record Name** fields. The **Object Name** must exactly match the required names listed above. Other fields may be configured according to your needs. 5. Repeat this process for each entity you want to synchronize. Create only the custom objects required for the entities you want to synchronize. ### Customers sync When enabled, Hyperline customers are synchronized with Salesforce accounts. You can select the synchronization direction (one-way or bidirectional). During the integration setup, Hyperline creates a **(Hyperline) Synchronize** checkbox custom field (`HyperlineSync__c` slug) on the Account object. Hyperline imports and synchronizes a Salesforce account only when this checkbox is enabled. Hyperline ignores accounts without it checked. ### Customer custom properties Customer custom properties use different paths for inbound and outbound synchronization: * **From Salesforce account fields to Hyperline**: Create a custom field on the Salesforce Account object whose API name matches the Hyperline custom property `slug`, followed by `__c`. When you synchronize customers from Salesforce, Hyperline imports this value into the matching existing customer custom property. Changes in Hyperline do not update this Salesforce field. * **From Hyperline to custom property value records**: Enable **Custom property values** in the integration settings. Hyperline creates one record in the `HyperlineCustomPropertyValue` custom object for each value and links customer values to the related Salesforce account. This option also keeps each property's name, type, and value available as separate fields. If a Hyperline customer custom property uses the `customer_tier` slug, create the `customer_tier__c` custom field on the Salesforce Account object. Set its value in Salesforce to import it into Hyperline when the customer syncs. The matching Salesforce account field must already exist, and the integration must be able to read it. Hyperline does not create it automatically. Synchronizing values through the custom object requires the `HyperlineCustomPropertyValue` object described above. ### Mapping Below are the default field mappings between Hyperline entities and Salesforce objects. Field mappings between Hyperline entities and Salesforce objects ### Turn customer fields on or off You can select which default customer fields Hyperline syncs. To stop syncing specific fields, for example if you manage the currency or billing address only in Salesforce, configure the customer field mappings. 1. In the Salesforce integration settings, go to the customer synchronization section. 2. Click **Configure field mappings**. 3. In the **Customer field mappings** modal, use the toggle next to each field to turn its sync on or off. Each field shows its fixed Salesforce destination (account field) below its name. 4. Click **Save changes**. Changes apply in the sync direction you configured. Disabled fields keep their existing values. Click **Cancel** to close the modal without saving. You can't turn off fields that Hyperline needs to identify and link customers. Their toggles are locked. Creating new customers may still require some fields to be synced. ### Manually trigger a sync You can also manually trigger customer data synchronization from the Hyperline customer page. In the **Integrations** dropdown, click **Sync with Salesforce** to push (or pull, depending on the sync direction) the customer's data and send all associated quotes, subscriptions, and invoices to Salesforce. ## Troubleshooting If data is missing or synchronization fails, open **Settings** > **Integrations** > **Salesforce** > **View issues** in Hyperline for details. ### Common issues **The component is empty with "Nothing yet" display and no button** This issue usually occurs when the Salesforce instance is not connected to the correct Hyperline environment (production vs. sandbox). In Salesforce, go to **Setup** > **Custom Code** > **Custom Settings**, click **Manage** for **Hyperline Settings**, then click **Edit**. Make sure the **Environment** field matches either `Production` or `Sandbox`, depending on your setup. **Embedded Hyperline views don't load, or an action loads forever** This happens when your browser blocks third-party cookies, which Hyperline needs to authenticate the embedded view inside your CRM. Allow third-party cookies for `[*.]hyperline.co`, then reload the page: Browsers block links to settings pages, so the addresses below aren't clickable. Copy the address and paste it into a new browser tab. * **Chrome / Arc**: open `chrome://settings/cookies`, then under "Sites allowed to use third-party cookies" add `[*.]hyperline.co` (or select "Allow all cookies"). See [Google's guide](https://support.google.com/chrome/answer/95647). * **Edge**: open `edge://settings/content/cookies` and add `[*.]hyperline.co` under "Allow". See [Microsoft's guide](https://support.microsoft.com/microsoft-edge/temporarily-allow-cookies-and-site-data-in-microsoft-edge-597f04f2-c0ce-f08c-7c2b-541086362182). * **Safari**: open Settings > Privacy and uncheck "Prevent cross-site tracking". See [Apple's guide](https://support.apple.com/guide/safari/manage-cookies-sfri11471). * **Firefox**: click the shield icon in the address bar and turn off "Enhanced Tracking Protection" for this site, or add an exception under Settings > Privacy & Security. See [Mozilla's guide](https://support.mozilla.org/kb/enhanced-tracking-protection-firefox-desktop). Also disable any browser extension that blocks cookies or trackers for this site. **The Salesforce component is empty (only the buttons appear, with no data)** This issue usually occurs when the same Salesforce ID is assigned to multiple customers in Hyperline. Hyperline uses the first matching customer it finds, but that customer may not contain any data. Ensure that the Salesforce ID is assigned to only one customer in Hyperline: the correct one. ## Disconnect You can disconnect the integration at any time by clicking **Disconnect** in the top-right corner of the Salesforce integration settings page. Disconnecting the integration stops all synchronization. The custom objects, custom fields, and any previously pushed data in Salesforce remain intact. Hyperline does not delete them. # Segment Source: https://docs.hyperline.co/integrations/segment Ingest usage events from Segment directly into Hyperline to drive usage-based billing without writing custom event-forwarding integrations. ## What is Segment? [Segment](https://segment.com) is a Customer Data Platform (CDP). It simplifies collecting and using data from the users of your digital properties (websites, apps, etc.). It allows you to collect, transform, send, and archive your first-party customer data. You can also enrich the customer data you collect by connecting data from your other tools. You can then aggregate it to monitor performance, inform decision-making processes, and create uniquely customized user experiences. You can easily send all this data to Hyperline to collect your customer's usage and automate usage-based billing and invoicing. ## Send usage from Segment to Hyperline To facilitate the transmission of usage data to Hyperline, we will generate and use a custom Function within Segment. Learn more about functions in [Segment's documentation](https://segment.com/docs/connections/functions). Replace the pre-written `onTrack` function in the code editor with the following code. The provided code will catch a Track event from Segment, and post it on Hyperline with the required properties picked from the Segment event. You can add any properties (with a value of type string, number, boolean, or array of the same types) you want to ingest in Hyperline by adding them in the `record` object. The field `my_property` is an example of an additional property pushed to Hyperline. ```javascript theme={null} async function onTrack(event, settings) { const endpoint = "https://ingest.hyperline.co/v1/events"; // https://docs.hyperline.co/api-reference/endpoints/billable-events/ingest-billable-event const event = { customer_id: event.userId, event_type: event.event, timestamp: event.timestamp, record: { id: event.messageId, my_property: event.properties.customProperty, // add any custom properties you want to ingest in Hyperline }, }; try { // Post request const response = await fetch(endpoint, { method: "POST", headers: { Authorization: `Bearer ${settings.apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify(event), }); // Retry on 5xx (server errors) and 429s (rate limits) if (response.status >= 500 || response.status === 429) { throw new RetryError(`Failed with ${response.status}`); } return response.json(); } catch (error) { // Retry on connection error throw new RetryError(error.message); } } ``` This code example will forward all event types to Hyperline. If you want to limit the events sent, you can use the Segment [Destination Filters](https://segment.com/docs/connections/destinations/destination-filters), or alternatively modify the code to filter out the data you don't want to send. In the provided code snippet, the API key is a secret configured within the **Settings** tab on the right panel. This approach helps you refrain from hard-coding private variables directly into the function. To implement this: 1. Click **Add Setting** 2. Input `API Key` as the label (resulting in the generated name `apiKey`) 3. Select the type `String` 4. Enter your Hyperline API key on the input on the right. You can generate a key with the [following guide](../api-reference/docs/authentication#generate-an-api-key). 5. Toggle the `Required` and `Sensitive` options 6. Save your setting Finalize the creation of the function with a name ("Test Function" in the example below) and an optional description. After creating the function, you can use it as a Destination of an existing source (in the example below it's the `Backend - Staging` source). Make sure to enable it to start receiving events from Segment in Hyperline. # Slack Source: https://docs.hyperline.co/integrations/slack Connect Slack to Hyperline to send automated billing notifications, alerts, and quote approval requests to your team's channels and direct messages. ## What is Slack? [Slack](https://slack.com) is a collaborative communication platform for teams, offering real-time messaging, file sharing, and integration with various tools. It organizes conversations into channels based on topics, projects, or teams, fostering efficient and organized team communication. ## Connect Slack to Hyperline You can connect Slack as a native integration in Hyperline to receive automated notifications in Slack channels and personal notification messages. To connect Slack: 1. Go to **Settings > Integrations** 2. Find **Slack** in the list of available integrations 3. Click **Connect** and authorize Hyperline to access your Slack workspace 4. Once connected, you can start creating notification rules If the Slack integration shows **Needs action**, reconnect Slack from the integration page. This can happen when Hyperline adds new Slack permissions required for the integration to work fully. ## Notification rules Notification rules let you automatically send Slack messages when specific events happen in Hyperline. Each rule combines a **trigger** (the event), a **Slack channel** (where to send), and a **message template** (what to send). To create a notification rule: 1. Go to **Settings > Integrations > Slack > Notifications** 2. Click **Add rule** 3. Give the rule a **name** 4. Select a **trigger** from the list of available events 5. Select the **Slack channel** where the notification should be sent 6. Customize the **message template** using variables 7. Save the rule Hyperline automatically attempts to join public Slack channels when you configure them in a notification rule. For private channels, you'll need to manually invite the Hyperline app to the channel. ## Quote approval requests in Slack When Slack is connected, quote approvers can receive approval requests directly in Slack through their personal notification settings. Slack approval request messages include the quote, customer, amount, quote owner, workflow, workflow step, and approvers. Hyperline also posts the quote PDF in a thread so approvers can review the document without leaving Slack. Approvers can: * Click **Approve** to approve the current workflow step * Click **Reject** to provide a rejection reason * Click **Open in Hyperline** to review the quote in Hyperline If the quote is already approved, rejected, or no longer waiting for that step, Hyperline refreshes the Slack message to show the current approval state. You can manage your personal Slack approval notifications from **Profile** > **Notifications**. Learn more about [quote approval workflows](/docs/quotes/approval). ### Available triggers You can create notification rules for the following events: | Trigger | Description | | - | - | | Approval requested | An approval step has been requested | | Approval request approved | An approval step has been approved | | Approval request rejected | An approval step has been rejected | | Bank account errored | A bank account encountered an error | | Data loader failed | A data loader job has failed | | Invoice chargeback | An invoice has been charged back | | Invoice errored | An invoice encountered an error | | Invoice late | An invoice is overdue | | Invoice settled | An invoice has been fully paid | | Quote signed | A quote has been signed | | Quote viewed | A quote has been viewed | | Subscription activated | A subscription has been activated | | Subscription contract renewed | A subscription contract has been renewed | | Subscription renewed | A subscription has been renewed | | Subscription trial ended | A subscription trial period has ended | | Subscription voided | A subscription has been voided | | Aggregator threshold crossed | An aggregator usage threshold has been crossed | ### Message template Each notification rule includes a customizable message template. You can format the message using **Markdown** and insert **dynamic variables** that will be replaced with actual values when the notification is sent. Variables are inserted using the `{{variableName}}` syntax. The available variables depend on the selected trigger. For example, an invoice trigger provides variables like `{{invoiceNumber}}` and `{{invoiceAmount}}`, while a quote trigger provides `{{quoteNumber}}` and `{{quoteValue}}`. You can also use **custom properties** in your message templates (e.g. `{{myCustomProperty}}`). Hyperline automatically attempts to join public Slack channels when you configure them in a notification rule. For private channels, you'll need to manually invite the Hyperline app to the channel. # Sphere Source: https://docs.hyperline.co/integrations/sphere Use Sphere as the tax engine for Hyperline: calculate US sales tax and VAT on your invoices, with one Sphere account per invoicing entity. ## Prerequisites You need to have a [Sphere account](https://getsphere.com). Hyperline uses one tax engine at a time per invoicing entity. If you use Sphere for an invoicing entity, Sphere calculates the tax of all its invoices, so configure your products and tax registrations in Sphere first. ## Setup Hyperline activates the Sphere integration on request. Contact us to enable it on your account, then follow the steps below. ### Get your Sphere API key 1. In your Sphere dashboard, open the API keys settings. 2. Create an API key for Hyperline and copy it. ### Connect Sphere 1. In Hyperline, go to **Settings** > **Integrations** and click **Connect** on the **Sphere** card. 2. Paste your API key and confirm. Hyperline checks the key with Sphere before saving the connection. The connection appears as **API key ending in** followed by the last characters of your key, so you can tell several connections apart. ### Assign invoicing entities A Sphere API key belongs to a single Sphere account. If your invoicing entities are registered in different Sphere accounts, connect one API key per account and assign each connection to its invoicing entities. 1. On the **Sphere** card, open the connection settings. 2. In **Invoicing entities**, select the entities whose tax this connection calculates, then save. To add another Sphere account, use **Connect another account** from the **Sphere** card menu. A connection with no invoicing entity assigned calculates tax for every entity that no other connection covers. An invoicing entity can only be assigned to one Sphere connection. ### Select Sphere as tax engine In the settings of your invoicing entity, click **Taxes** and select **Sphere** as tax engine. Sphere is selectable once a connection is verified. ### Configure products Sphere reads the tax code of each invoice line from its Sphere product. Hyperline sends each line to Sphere under the ID of its Hyperline product. The first time Sphere sees a product, it creates it in your account with your account's default tax code. In your Sphere dashboard, open each product created by Hyperline and give it the tax code you want to apply. Until you set its tax code in Sphere, a product is taxed with your account's default tax code. Invoice lines without a Hyperline product are taxed against the Sphere product `default_hyperline_product_sphere`. ## How taxes are calculated For each invoice, Hyperline sends Sphere the customer's address, tax ID, and invoice lines, and stores the tax Sphere returns on each line. * **Address**: Sphere uses the invoice's shipping address when there is one, otherwise the billing address. See [shipping address](/docs/subscriptions/create) for how a subscription's shipping address is selected. * **Tax ID**: when the customer has a tax ID, Sphere applies the reverse charge where it is due, and the invoice shows the reverse-charge statement. * **Exemptions**: when Sphere reports a product as exempt in the customer's jurisdiction, Hyperline marks the line as exempt. * **Tax-exempt customers**: Hyperline doesn't send customers marked as tax-exempt to Sphere and invoices them without tax. The tax rate shown on an invoice is the tax amount divided by the amount excluding tax. In the US, it can differ from the jurisdiction's headline rate. For example, a state may tax only part of the price of a product, or state, county, and city taxes may add up. In Texas, SaaS is taxed on 80% of its price. For an invoice of \$100 shipped to Austin, where the combined rate is 8.25%, Sphere calculates \$6.60 of tax and the invoice shows a 6.6% tax rate. If Sphere cannot locate the customer's address, Hyperline creates the invoice without tax. Complete the customer's address, then edit the draft invoice and choose to update the customer details to recalculate its tax. ## Limitations * Hyperline uses Sphere to calculate tax only. Hyperline doesn't record invoices and credit notes as transactions in Sphere. * To disconnect a Sphere connection, contact us. # Stripe Source: https://docs.hyperline.co/integrations/stripe Collect card, ACH, SEPA, and Apple Pay payments through Stripe on Hyperline with one-click connection, customer sync, and full reconciliation. ## Prerequisites You need to have a [Stripe](https://stripe.com) account, finished Stripe's onboarding flow, and admin rights on Hyperline. ## Setup If [Stripe](https://stripe.com) is your preferred Payment Service Provider, connecting it with Hyperline is a straightforward process: 1. In the menu, select **Settings** 2. Select **Payment** 3. Click **Connect payment provider**, then Stripe This will redirect you to the Stripe login page where you will have to enter your account credentials and click **Continue**. Once the process is completed, you will see Stripe appearing as **Active** in the Payment page. You can connect multiple Stripe accounts to Hyperline so that payments are routed based on your invoicing entities and preferences. ## Payment methods Stripe through Hyperline supports: * **Card** payments from major card schemes such as Visa, Mastercard, American Express, Discover & Diners, China Union Pay, eftpos, girocard, Interac, JCB and Maestro, depending on country and locality * **Direct Debit** payments including SEPA (EU), Bacs (UK), or ACH (US) * **Stripe Link** for faster checkout with saved payment details ## Customer information Each time you bill a customer in Hyperline, the corresponding customer profile and payment details (including payment methods and mandates) are automatically created and managed by Hyperline in your Stripe account. Additionally, Hyperline integrates payment method collection forms into our hosted pages (checkout, customer portal, invoice page, and quote page), requiring no technical effort on your part. This seamless integration ensures that customer data and payments remain synchronized between Hyperline and Stripe, streamlining transaction management and customer information handling. ## Importing existing Stripe data If you already have a Stripe account with existing customers, payment methods, products, prices, or subscriptions, Hyperline can import this data during setup. This is particularly useful when you are moving existing billing operations into Hyperline. Before importing, check these points: * Import prices before creating subscriptions that depend on them, including prices in a new currency such as CHF. * Subscriptions with the same Stripe product on multiple lines may be skipped during import. Consolidate the lines in Stripe, or use distinct products for each line, then run the import again. * Use your sandbox account first when validating the import flow or checking integration behavior. Please contact support before importing existing Stripe data. The team can confirm the expected scope and help you review skipped records after the import. # Xero Source: https://docs.hyperline.co/integrations/xero Push invoices, credit notes, customers, and payments from Hyperline to Xero accounting with automatic product mapping and tax code synchronization. [Xero](https://www.xero.com) is a New Zealand–based technology company that provides cloud-based accounting software for small businesses. ## Prerequisites You need to have a valid [Xero account](https://www.xero.com) and admin rights on Hyperline. ## Setup If you are not already logged into Xero, enter your Xero credentials to proceed. Select the organisation you want to link to Hyperline, then click **Allow access**. By default, **your default invoicing entity** will be linked to this organisation. If you want to link a different entity, please contact our support team. Your Hyperline account is ready to send invoices and credit notes. ## Reconcile Hyperline and Xero customers If you already have existing customers in Xero, we'll need to link them with the corresponding customers in Hyperline. Our support team is available to assist you with this process during onboarding. ## Synchronization When you connect your Xero account, Hyperline **automatically sends invoices** with their complete details (including line items and PDF file). By default, only invoices and customers created after the connection date will sync. If you need to push older data to Xero, please contact our support team. ### Invoice PDF synchronization Invoice PDFs are automatically attached to invoices in Xero when they are first synced. If you need to re-attach or update PDFs for existing invoices (for example, if the initial attachment failed), please contact our support team. ### Customer synchronization Hyperline supports 2 modes of synchronization for customers: * **no synchronization**: customers are not synchronized with Xero. * **from Hyperline to Xero**: customers created in Hyperline are automatically created in Xero with their details. When a customer is updated in Hyperline, the changes are automatically synced to Xero in real-time. ### Payment synchronization Hyperline supports 3 modes of synchronization for payments: * **no synchronization**: payments are not synchronized with Xero. * **from Hyperline to Xero**: payments created in Hyperline are automatically created in Xero and associated to the corresponding invoice. * **from Xero to Hyperline**: payments created in Xero are automatically created in Hyperline, and the status of the invoice is updated accordingly. The synchronization delay is 5 minutes maximum. ## Synchronization rules Synchronization rules select the Xero revenue account for each invoice or credit note line. They let you vary the account by product, currency, country, or tax treatment without changing the product mapping for every case. 1. Open **Settings > Integrations > Xero**. In **Synchronisation rules**, open the rule count card or **No rules configured**, then click **Add rule**. 2. Select the **Invoicing entity** if prompted and enter a descriptive **Name**. 3. Under **Applied on**, add filters. Available filters include products, product type, coupons, currency, country, tax scheme, tax territory, tax rate class, billing interval, invoice types, and custom properties. 4. Under **Account configuration**, select a **Revenue account**. Use **Sync accounts from Xero** if you need to refresh the account list. 5. Click **Save changes**. Hyperline selects the line's account in this order: 1. The account supplied by a matching synchronization rule. 2. The product's account code, if no rule supplies an account. 3. The integration's default **Invoice account code** or **Credit note account code**. Leave filters empty for a default rule. At the same priority, a rule scoped to a matching product takes precedence over the default. Avoid overlapping rules with conflicting accounts. Create a default rule for subscription revenue and a second rule filtered to your API usage product. Select a usage revenue account on the second rule to separate usage charges in Xero. Payments continue to use the integration's **Payment account code** setting. Xero does not offer transaction or journal selection in the synchronization rule form. ## Manage the integration To reauthorize, reconfigure, resync, or disconnect this integration, see [Manage connected integrations](./manage-integration). ## Settings Please contact our support team if you wish to change these settings. * **Invoice account code**: by default, invoices are created in Xero using the account code *200*. * **Credit note account code**: by default, credit notes are created in Xero using the account code *200*. * **Payment account code**: by default, payments are created in Xero using the account code *001*. ## Product and account codes Xero supports associating a product code and an account code to every invoice line item. You will need to configure the product code and the General Ledger account code for every product that you intend to invoice in Xero, in the **Products > Advanced settings** section. When no synchronization rule supplies an account, Hyperline uses the product account code, then the default invoice or credit note account code. # Automate Hyperline with Zapier Source: https://docs.hyperline.co/integrations/zapier Connect Hyperline to thousands of apps using Zapier: automate customer creation, invoice events, and subscription updates without writing code. ## What is Zapier? [Zapier](https://zapier.com) is an online automation tool that connects your apps and services. You can connect two or more apps to automate repetitive tasks without coding or relying on developers to build the integration. You can use Zapier to connect Hyperline to heaps of other tools your team is using such as your CRM, your accounting software, your product, and more. ### What is a Zap? A Zap is an automated workflow that connects your apps and services together. Each Zap consists of a trigger and one or more actions. When you turn your Zap on, it will run the action steps every time the trigger event occurs. ### Trigger and action A trigger is an event that starts a Zap. An action is an event a Zap performs after it is triggered. For example, if you want to create an account in your CRM each time a customer is created in Hyperline, the trigger is "Customer Created". This trigger starts the action "Create an account in CRM". You can use the Hyperline app in Zapier to automate things like creating new customers from CRM, sending invoices to your accounting software, or pushing usage data into Hyperline. [Learn more about the basics of using Zapier.](https://zapier.com/resources/guides/quick-start/automation-basics) ### Available triggers The Hyperline Zapier app can start a Zap from several Hyperline events. The exact list available in Zapier depends on your app version, but the most common triggers are: | Trigger | When it runs | | - | - | | **Customer Created** | A customer is created in Hyperline. | | **Invoice Created** | An invoice is created in Hyperline. | | **Invoice Ready** | An invoice is finalized and ready to be paid. | | **Invoice Paid** | An invoice is settled. | | **Subscription Created** | A subscription is created. | | **Subscription Activated** | A subscription becomes active. | | **Payment Method Created** | A customer adds or starts adding a payment method. | | **Payment Method Activated** | A payment method becomes usable for future payments. | | **Payment Method Deleted** | A payment method is removed from the customer. | If your automation needs to react as soon as a customer enters a payment method, listen to **Payment Method Created**. **Payment Method Activated** only runs once the payment method is confirmed and usable. ### More resources There are lots of helpful guides in Zapier's help center, but here are some of the most useful ones to refer to when using our Zapier app: * [Learn key concepts in Zapier](https://help.zapier.com/hc/en-us/articles/8496181725453) * [Automation basics](https://zapier.com/resources/guides/quick-start/automation-basics) * [Using Filters in Zaps](https://help.zapier.com/hc/en-us/articles/8496276332557) * [Using Formatter in Zaps](https://help.zapier.com/hc/en-us/articles/8496212590093) * [Troubleshooting errors in Zaps](https://help.zapier.com/hc/en-us/articles/8496037690637) ## Connect Hyperline and Zapier Here's how to connect Hyperline to Zapier: 1. Log in to your [Zapier account](https://zapier.com/app/login) or [create a new account](https://zapier.com/sign-up) 2. Navigate to **Zaps** from the left sidebar 3. Click **+ Create**, search for "Hyperline", and select it Zapier integration is in private access, so you might not see it the first time you search for it. To access the invite link, click the 'Connect' button on the Zapier card in the Settings > Integrations page of your Hyperline account. 4. Zapier asks you to **Sign in** and prompts you to add an API Key, which you can [learn how to generate in Hyperline here](/api-reference/docs/authentication). 5. Once you've added it in Zapier, click **Yes, Continue to Hyperline**. When this is completed you can start creating all the automation you want! Creating a Zap requires no coding knowledge, and Zapier walks you step-by-step through the setup. By default, this connection to Hyperline is private and only you can use it. If you'd like to share it with your team, click **Share**. Add the members or teams you want to share it with, or select **Share with everyone**, then click **Done**. [Learn more about sharing app connections.](https://help.zapier.com/hc/en-us/articles/8496326497037-Share-app-connections-with-your-team) Follow [this example guide](./slack) to set up a Zap that sends your business metrics to a Slack channel regularly. # Zendesk Source: https://docs.hyperline.co/integrations/zendesk Connect Zendesk with Hyperline to bring ticket history, statuses, priorities, tags, and messages into customer intelligence analyses. [Zendesk](https://www.zendesk.com) is a customer service platform for managing support tickets across email, chat, and other channels. Connecting Zendesk lets Hyperline attach support tickets to the matching Hyperline customers. The customer monitoring agent can then weigh unresolved issues and support pressure alongside contract, invoice, payment, and usage data. Zendesk is part of [Customer intelligence](../docs/customer-intelligence/overview), a paid add-on. The Zendesk card only appears in **Settings > Integrations** when Customer intelligence is enabled for your account. Contact the Hyperline team through the in-app chat to enable it. ## Prerequisites * A valid [Zendesk account](https://www.zendesk.com) and your Zendesk subdomain, the `acme` part of `acme.zendesk.com`. * A Zendesk user allowed to authorize applications for your account, usually an administrator. * Admin rights on your Hyperline account. ## Connect Zendesk Type the subdomain only, without `.zendesk.com`. Your Zendesk account decides where the authorization happens, so Hyperline needs it before redirecting you. You are redirected to your own Zendesk domain. Sign in if needed, review the requested access, and confirm. You are redirected back to Hyperline and the integration appears as connected. ### Requested permissions Hyperline requests Zendesk's account-wide **read** permission. Narrower Zendesk permissions were tried first and do not work: the Zendesk search API, which Hyperline uses for customers without an explicit organization mapping, rejects them. The broad read permission is the narrowest grant under which the sync actually runs. It stays read-only, and Hyperline never creates, edits, or deletes anything in Zendesk. ## What Hyperline fetches For every matched ticket, Hyperline stores: | Data | Details | | - | - | | Ticket | Zendesk ticket identifier, subject, and a short preview of the description | | Status | Normalized to `open`, `closed`, or `snoozed` | | Priority | Urgent, high, normal, or low | | Tags | The ticket tags, used as labels | | Requester | Name and email of the person who opened the ticket | | Dates | Creation date and last update date | | Comments | Each comment with its body, author name and email, and date | Internal comments are synced alongside public replies and stored as notes. Anything written on a ticket in Zendesk can therefore be used as context by the monitoring agent. ### Which tickets are matched Hyperline resolves tickets per customer, in this order: 1. If the customer is linked to a Zendesk **organization**, Hyperline lists that organization's tickets. 2. Otherwise, Hyperline searches tickets whose requester uses an email address on the customer **Domain**. Hyperline skips public email domains, such as `gmail.com`: a domain-wide search on them would match tickets from unrelated people. Keep customer **Domain** values up to date, and link the Zendesk organization on the customer page when you have one. The organization link is the more precise of the two. ## Synchronization Hyperline synchronizes Zendesk once a day, and also refreshes a customer on demand when the customer monitoring agent analyzes it. Synchronization is incremental: a thread whose messages have not changed since the last run is not fetched again. ## Where Zendesk data appears * **Customer page**: the **Integrations** section shows a Zendesk row with the most recent thread. Open it to browse synced tickets with their statuses, labels, and messages. * **Monitoring agent**: enable Zendesk from the agent's **Connectors** tab. See [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent). * **Analysis results**: Zendesk appears under **Data sources** when support context was used. ## Manage the integration Open **Settings > Integrations** and select **Zendesk**. Synchronization errors are reported on this page. * **Reauthorize** refreshes the connection when the authorization expires or is revoked. * **Disconnect** stops synchronizing new tickets. ## Related * [Customer intelligence](../docs/customer-intelligence/overview) * [Customer monitoring agent](../docs/customer-intelligence/customer-monitoring-agent) * [Integrations overview](./overview) # Zoho Books Source: https://docs.hyperline.co/integrations/zoho-books Push invoices, credit notes, customers, and payments from Hyperline to Zoho Books accounting with automatic chart of accounts and tax mapping. [Zoho Books](https://www.zoho.com/books) is a cloud-based accounting software developed by Zoho Corporation. ## Prerequisites You need to have a valid [Zoho Books account](https://www.zoho.com/books) and admin rights on Hyperline. ## Setup If you are not already logged into Zoho Books, enter your Zoho credentials to proceed. Your Hyperline account is ready to send invoices and credit notes. ## Reconciling data ### Customers To link an existing Zoho Books customer to a Hyperline customer, navigate to the customer details page, click the "Edit" button in the "Integrations" section, and enter the Zoho Books customer ID. For bulk operations during initial setup, contact our support team or use [this API endpoint](../api-reference/endpoints/customers/bulk-update-providerscustomers-mapping.mdx). ### Products You need to map your Zoho Books products (items) to your Hyperline product catalog. For each product in Hyperline, go to the Accounting section and enter the corresponding Zoho Books item name in the "Product code" field. When specified, Hyperline automatically attaches each invoice line item to the corresponding item in Zoho Books. Zoho Books requires all Hyperline invoice line items to be mapped to Zoho Books items. If a product is not mapped, the invoice will not be created in Zoho Books. ## Synchronization When you connect your Zoho Books account, Hyperline **automatically sends invoices** with their complete details (including line item details). By default, only invoices and customers created after the connection date will sync. If you need to push older data to Zoho Books, please contact our support team. ### Customers Hyperline supports 2 modes of synchronization for customers: * **no synchronization**: customers are not synchronized with Zoho Books. * **from Hyperline to Zoho Books**: customers created in Hyperline are automatically created in Zoho Books with their details. ### Payments Hyperline supports 3 modes of synchronization for payments: * **no synchronization**: payments are not synchronized with Zoho Books. * **from Hyperline to Zoho Books**: payments created in Hyperline are automatically created in Zoho Books and associated to the corresponding invoice. * **from Zoho Books to Hyperline**: payments created in Zoho Books are automatically created in Hyperline, and the status of the invoice is updated accordingly. Synchronization occurs within 5 minutes. ## Synchronization rules Synchronization rules select the Zoho Books account for each invoice or credit note line. Product mappings remain required: the rule supplies the account while the product mapping identifies the Zoho Books item. 1. Open **Settings > Integrations > Zoho Books**. In **Synchronisation rules**, open the rule count card or **No rules configured**, then click **Add rule**. 2. Select the **Invoicing entity** if prompted and enter a descriptive **Name**. 3. Under **Applied on**, filter by products, product type, coupons, currency, country, tax scheme, tax territory, tax rate class, billing interval, invoice types, or custom properties. 4. Under **Account configuration**, select a **Revenue account**. Use **Sync accounts from Zoho Books** to refresh the available accounts. 5. Click **Save changes**. Hyperline matches the resolved account code to your Zoho Books chart of accounts and sends the corresponding account on the line. A matching rule's account takes precedence over the product account code. Make sure the selected code exists in the connected Zoho Books organization. Leave filters empty for a default rule. At the same priority, a rule scoped to a matching product takes precedence over the default. Avoid overlapping rules with conflicting accounts. Map your implementation service to its Zoho Books item, then create a rule filtered to that product and select your services revenue account. The invoice line keeps its item mapping and uses the rule's account. Transaction and journal rules are not available for Zoho Books. Invoice account rules do not change payment synchronization settings. ## Manage the integration To reauthorize, reconfigure, resync, or disconnect this integration, see [Manage connected integrations](./manage-integration).