4. Copy the key and it in a safe space, you won't be able to see it later in Hyperline
This doc assumes that you already have a basic working knowledge of [React](https://react.dev/) and that you have already set up a React project.
## Getting started
## Components
### Subscriptions
List all active subscriptions
```tsx
### Variables
They are meant to customise all elements at once.
| Variable name | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `borderRadius` | Change the roundness of the elements: Buttons, tables, ... |
| `colorBackground` | Most elements have a transparent background. In other cases, you can customise the background color of the element |
| `colorPrimary` | Color used for buttons and accent text |
| `colorPrimaryHover` | Hover color for buttons |
| `colorPrimaryDisabled` | Color of disabled buttons |
| `colorBorder` | The color of all our regular borders |
| `colorText` | Default text color |
| `colorTextSecondary` | Text color of secondary text |
| `fontFamily` | Font used. If you need to import a font, please read the next section |
### Fonts
Set your application's font.
* `src` Url of the font file
* `family` Name of the font - this is the name you'll use for the `fontFamily` variable
```ts
That's it! You will now receive webhook calls when the event occurs on the Hyperline system.
## Event types
After sending an example event, you can click into the message to view the message payload, all of the message attempts, and whether it succeeded or failed.
Additionally, the Logs section is here to help you have a complete view of past call attempts with their date, status, and payload.
## Event delivery
### Replaying events
If you want to replay a single (or multiple) events, you can find the message from the UI, open the options menu next to any of the attempts, and click on "Resend".
It's a great help if your service had downtime or if your endpoint was misconfigured.
### Retry schedule
Each message is attempted based on the following schedule, where each period is started following the failure of the preceding attempt:
* Immediately
* 5 seconds
* 5 minutes
* 30 minutes
* 2 hours
* 5 hours
* 10 hours
* 10 hours (in addition to the previous)
If an endpoint is removed or disabled delivery attempts to the endpoint will be disabled as well.
### 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. We recommend designing your system in a way that doesn't require ordering. Additionally, you can 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).
## Best practices
### Handling 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
As webhooks can be retried, another update can occur once your server is finally able to process the event. Therefore, we advise you to query the latest version of the related entity upon receiving a webhook.
### Verify webhooks
Verifying webhooks is an important part of the consumption. 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.
In order to prevent it, every webhook and its metadata is **signed** with a unique key for each endpoint. This signature can then be used to verify the webhook indeed comes from Hyperline, and only process it if it is.
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 will pass signature validation, and will therefore be acted upon.
To mitigate this attack, a timestamp (`webhook-timestamp` header) is included in every request for when the webhook attempt occurred. We recommend you 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 are used for verification:
* `webhook-id`: the unique message identifier for the webhook message. This identifier is unique across all messages but will be the same when the same webhook is being resent (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**
The content to sign is composed by concatenating 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 changes, so even a small change in the body will cause the signature to be completely different. This means that you should not change the body in any way before verifying.
**Determining the expected signature**
`HMAC` with `SHA-256` is used to sign webhooks.
So to calculate the expected signature, you should HMAC the `signed_content` from above using the base64 portion of your signing secret (this is the part after the `whsec_` prefix) as the key. 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
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 is composed of 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.
# Get analytics
get /v1/analytics
Retrieve your pre-computed account's analytics (ARR, revenues, churn, etc).
# Create billable event
post /v1/events
Create a new billable event.
# Create billable events
post /v1/events/batch
Create several billable events in batch (limited to max 5000 events per request).
# Ingest and calculate billable event prices
post /v1/events/prices
Ingest and calculate prices for a single billable event. This endpoint is in beta, please contact us if you want to know more.
# simulate billable event prices
post /v1/events/simulate-prices
Simulate prices for a single billable event. This endpoint is in beta, please contact us if you want to know more.
# Create company
post /v1/companies
Create a new company to which the authentication token will have access to.
# Get companies
get /v1/companies
Retrieve all companies that the authentication token has access to.
# Create coupon
post /v1/coupons
Create a new coupon.
# Delete coupon
delete /v1/coupons/{id}
Delete an existing coupon.
# Get coupon
get /v1/coupons/{id}
Retrieve the details of an existing coupon.
# Get coupons
get /v1/coupons
Retrieve all existing coupons.
# Update coupon
put /v1/coupons/{id}
Update the details of an existing coupon.
# Create custom property
post /v1/custom-properties
Create a new custom property.
# Delete custom property
delete /v1/custom-properties/{id}
Delete an existing custom property.
# Get custom properties
get /v1/custom-properties
Retrieve all custom properties previously created.
# Update custom property
put /v1/custom-properties/{id}
Update an existing custom property.
# Create credit product
post /v1/customers/{id}/credits
Create a credit entity for a given product with an optional balance for a customer.
# 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 product
get /v1/customers/{id}/credits/{productId}
Retrieve the details of an existing credit product for a customer.
# List credit products
get /v1/customers/{id}/credits
List all credits products attached to a customer.
# List credit transactions
get /v1/customers/{id}/credits/{productId}/transactions
Retrieve all credit transactions associated with a credit product for a specific customer.
# Purchase credits
post /v1/customers/{id}/credits/{productId}/purchase
Purchase a number of credits. This action will generate an invoice and charge the customer. Can take a few seconds to complete.
# Topup credits
post /v1/customers/{id}/credits/{productId}/topup
Topup a number of free credits. This action will not charge the customer.
# Delete payment method
delete /v1/customers/{id}/payment-methods/{paymentMethodId}
Delete an existing customer payment method.
# Get payment method
get /v1/customers/{id}/payment-methods/{paymentMethodId}
Retrieve the details of an existing customer payment method.
# List payment methods
get /v1/customers/{id}/payment-methods
List all payment methods attached to a customer.
# Archive customer
put /v1/customers/{id}/archive
Archive an existing customer.
# Bulk update providers/customers 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
post /v1/customers
Create a new customer.
# Delete customer
delete /v1/customers/{id}
Delete an existing customer. The customer must be archived prior to the deletion.
# Get customer
get /v1/customers/{id}
Retrieve the details of an existing customer.
# Get customer portal
get /v1/customers/{id}/portal
Retrieve the URL of the customer portal.
# Get customer tax rates
get /v1/customers/{id}/taxes/rates
Retrieve the eligible tax rates for a customer.
# Get customers
get /v1/customers
Retrieve all existing customers.
# Unarchive customer
put /v1/customers/{id}/unarchive
Unarchive an archived customer.
# Update customer
put /v1/customers/{id}
Update the details of an existing customer.
# Create component token
post /v1/integrations/components/token
Create a new token for embedded components.
# Create invoice
post /v1/invoices
Create a new invoice.
# Create transaction
post /v1/invoices/{id}/transactions
Manually create a transaction linked to an existing invoice to mark it as paid/partially paid
# Download invoice
get /v1/invoices/{id}/download
Download the PDF of an existing invoice.
# Get invoice
get /v1/invoices/{id}
Retrieve the details of an existing invoice.
# Get invoices
get /v1/invoices
Retrieve all existing invoices. By default, invoices with status `open` are not included.
# Update invoice
patch /v1/invoices/{id}
Update an invoice in draft or grace_period status.
# Validate draft invoice
post /v1/invoices/{id}/validate
Send a draft invoice for payment, set the status to `to_pay` and its number. This is not reversible.
# Void invoice
post /v1/invoices/{id}/void
Void an invoice in a `to_pay` status. This action generates a corresponding credit note.
# Create invoicing entity
post /v1/invoicing-entities
Create a new invoicing entity to send invoices from.
# Delete invoicing entity
delete /v1/invoicing-entities/{id}
Soft deletes an invoicing entity. This action won't delete the associated invoices.
# Get invoicing entities
get /v1/invoicing-entities
Retrieve all invoicing entities for your current client.
# Get invoicing entity
get /v1/invoicing-entities/{id}
Retrieve a specific invoicing entity.
# Update invoicing entity
put /v1/invoicing-entities/{id}
Update an existing invoicing entity.
# Authorize
get /v1/oauth/authorize
Redirects the user to the Hyperline's login page, and grants authorization to your integration.
# Generate tokens
post /v1/oauth/tokens
Exchange an auth code received at the authorize endpoint for an actual access token, or refresh it.
# Get user info
get /v1/oauth/userinfo
Returns the user information associated with an access token.
# Revoke token
post /v1/oauth/revoke
Revoke a refresh token. Once revoked the token can not be used anymore.
# Get organisation
get /v1/organisations/{id}
Retrieve the details of an existing organisation.
# Patch organisation
patch /v1/organisations/{id}
Update the details of an existing organisation.
# 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
# Get plan
get /v1/plans/{id}
Retrieve the details of an existing plan.
# Get plans
get /v1/plans
Retrieve all existing plans.
# Update prices
put /v1/price-configurations/{id}/prices
Update prices of an existing price configuration.
# Create product
post /v1/products
Create a new product.
# Get product
get /v1/products/{id}
Retrieve the details of an existing product.
# Get products
get /v1/products
Retrieve all existing products.
# Update product
put /v1/products/{id}
Update the details of an existing product.
# Create quote
post /v1/quotes
Create a new quote.
# Download quote
get /v1/quotes/{id}/download
Download an existing quote.
# Download quote file
get /v1/quotes/{quoteId}/files/{id}/download
Download a file (attachment or manually signed file) attached to an existing quote.
# Get quote
get /v1/quotes/{id}
Retrieve the details of an existing quote.
# Get quotes
get /v1/quotes
Retrieve all existing quotes.
# Send quote
post /v1/quotes/{id}/send
Send an existing quote by email for signature.
# Sign quote
post /v1/quotes/{id}/sign
Manually mark the quote as signed externally. Built-in Hyperline signature flow won't be used.
# Void quote
post /v1/quotes/{id}/void
Void an existing quote.
# Activate subscription
post /v1/subscriptions/{id}/activate
Manually start a subscription for the first time.
# Cancel subscription
post /v1/subscriptions/{id}/cancel
Cancel an existing subscription.
# Create subscription
post /v2/subscriptions
Create a new subscription and assign it to a customer.
# Create subscription update
post /v1/subscriptions/{id}/update
Create an update to apply on an existing subscription.
# Create subscription updates
post /v1/subscriptions/{id}/update-many
Create multiple updates to apply at once to an existing subscription.
# Get subscription
get /v2/subscriptions/{id}
Retrieve the details of an existing subscription.
# Get subscriptions
get /v2/subscriptions
Retrieve all existing subscriptions.
# Pause subscription
post /v1/subscriptions/{id}/pause
Pause a subscription.
# Reactivate subscription
post /v1/subscriptions/{id}/reactivate
Reactivate a paused subscription.
# 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
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
post /v1/subscriptions/{id}/reinstate
Reinstate an existing subscription scheduled for cancellation.
# Transition subscription to next phase
post /v2/subscriptions/{id}/next-phase
Update a subscription and transition it to the next available phase.
# Update subscription
put /v2/subscriptions/{id}
Update parameters for a subscription.
# Get tax rate
get /v1/taxes/rates/{id}
Retrieve the details of an existing custom tax rate.
# Get tax rates
get /v1/taxes/rates
Retrieve all existing custom tax rates.
# Create app
post /v1/apps
Create a new third-party app.
# Delete app
delete /v1/apps/{id}
Delete an existing third-party app.
# Get apps
get /v1/apps
Retrieve all existing third-party apps.
# Update app
put /v1/apps/{id}
Update an existing third-party app.
# Create wallet
post /v1/wallets
Create a new wallet.
# Get wallet
get /v1/wallets/{id}
Retrieve the details of an existing wallet.
# Get wallet settings
get /v1/wallets/settings
Retrieve the wallet settings.
# Get wallet transactions
get /v1/wallets/{id}/transactions
Retrieve all transactions of an existing wallet.
# Get wallets
get /v1/wallets
Retrieve all existing wallets.
# Load wallet
post /v1/wallets/{id}/load
Load credits on an existing wallet.
# Update wallet
put /v1/wallets/{id}
Update the details of an existing wallet.
# Update wallet settings
put /v1/wallets/settings
Update the wallet settings.
# Create webhook endpoint
post /v1/webhooks/endpoints
Create a new webhook endpoint.
# Delete webhook endpoint
delete /v1/webhooks/endpoints/{id}
Delete an existing webhook endpoint.
# Get webhook endpoint
get /v1/webhooks/endpoints/{id}
Retrieve an existing webhook endpoint.
# Get webhook endpoints
get /v1/webhooks/endpoints
Retrieve all webhook endpoints.
# Get 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
put /v1/webhooks/endpoints/{id}
Update an existing webhook endpoint.
# Product updates May, 2023
## Coupons
Our most requested feature so far is out, you can now assign coupons to customers on Hyperline.
Two types of coupons are available (%-based or amount-based) with plenty of configuration options to choose from.
We also invested time it making it really easy to attach coupons to subscriptions and immediately see the impact.
You'll also be able to attach coupons to specific items depending on your need.
And of course, they're displayed in our invoice and our hosted portals.
## Stripe direct debit
You can now use Stripe as a direct debit provider for SEPA payments.
The integration is done seamlessly in our hosted flows, you just have to switch on the direct debit payment method in your settings once Stripe is connected.
## Improved events page
We have rebuilt our events debugging page from the ground up, making it really easy to explore synchronised events. We've also added for you a “delete” action to remove unwanted events from our database.
## New invoices page
A brand new page has appeared in your sidebar: Invoices. After getting a lot of feedback that invoices weren't really easy to find, we decided to group them together in a single page. We'll soon add export capabilities as well as metrics on your revenue, outstanding invoices, and more.
## One-time payments checkout
You can now create a one-time payment for a customer without a subscription and we'll generate a checkout session and an invoice for you.
To access it click on the customer menu (the 3 dots on the top right of the page) and select “Charge a one-time payment”.
Payment methods selection is only available for checkout-based payments and not for immediate charges.
## Custom domain for hosted pages
We didn't expect it, but 100% of our customers adopted the feature as soon as it was available. You can now configure your own domain for checkout and portal links.
Some good domain ideas we've seen:
* subscribe.acme.io
* buy.acme.io
* billing.acme.io
* getstarted.acme.io
To activate it, you'll need access to your domain DNS configuration and to do a small action on our settings page.
## Subscriptions API
You can now assign subscriptions through our public API. We've made it easy yet configurable so you won't get headaches during the integration phase.
You can find the documentation [here](../api-reference/endpoints/subscriptions/create-subscription) and don't hesitate to reach out to us if you need anything.
# Product updates June, 2023
## Wallets
Wallets allow you and your customers to pre-pay into a balance that's automatically used by Hyperline's system when paying invoices. This feature is particularly useful when you want to set up upfront payments and/or pay-as-you-go flows.
There are two types of top-up: paid ones (billed to your customer), free (offered to your customer).
We also invested time to make sure your customers are autonomous in using wallets by allowing them to see their wallet balance, top-up, and see the future projected wallet debits (next subscription to pay) on their dedicated portal page.
As you can also see, we refreshed the UI of the portal page to make it shinier.
The invoice has been updated accordingly to display all the payment methods used to pay it (wallets + credit card for example).
## Subscriptions seats count increase
We now allow you and your customers to change the number of seats included in an active subscription.
Your customers are autonomous in increasing the number of included seats on their hosted portal page, while you can increase **and** decrease this value on your customer view page.
## Brand new settings
As you may have already seen, we fully revamped the UI and hierarchy of the settings part of the app.
This includes clearer sections and structure, alignment with our UI brand, and a contextual right panel with help/FAQ explanations or an invoice preview to see in real-time the impact of the setting values on your future invoices look and feel.
We'll continue to rollout a new page structure to all pages in the product in the coming weeks.
## Data loaders improvements
We've invested a lot of hidden work and made many improvements in our events ingestion system through data loaders, which make it more reliable and performant (capable of ingesting millions of events).
This is mainly beneficial to our customers with dynamic/usage-based pricing models.
## Webhooks
Our most requested feature by our API customers is finally out! You can now receive webhook events from Hyperline and create deeper integrations with your product flows.
This capability comes with a set of developer tools: testing events send, audit logs and activity insights, visual replay, retry, signature, alongside a catalog describing all the available events (related to invoices, subscriptions and wallets for now).
*[More details in the documentation](../api-reference/docs/webhooks)*
# Product updates July, 2023
## New dashboard
Let’s face it, the previous dashboard didn’t look good… so we revamped it! You get all your key business metrics in a single place.
ARR is calculated every 5 minutes based on live customers consumptions and churn is computed in realtime when you’re opening Hyperline.
## New invoice details page
It’s easier to look at an invoice directly in the app than in the PDF file right? That’s why we’ve added a new invoice details page, accessible by clicking on any invoice table row in the product.
We’ve added a transactions table (with details when an error occurs) and providers fees (nothing is hidden anymore 😉).
## Purchase order
You can now assign a purchase order number to subscriptions and one-off payments. Purchase orders will show on the final PDF invoice and on the invoice page directly.
## New email for transfer payment
Make your payments by bank transfer even easier!
We now automatically send the invoice to be paid by e-mail to your customer when he chooses to pay by transfer.
## New public API endpoints
You can now [create products](../api-reference/endpoints/products/create-product) and [update prices](../api-reference/endpoints/price-configurations/update-prices) through the public API.
We’re making changes to our product catalog and this API is already compatible with the future data models.
## New webhooks
We also added new webhooks related to **customer creation and updates**. This allows you to build you own custom integration either by listening those events in your product or use no-code tools like Zapier or n8n to plug updates into external tools (like your CRM).
## General Availability of Mollie
At Hyperline, our vision is to stay agnostic from the payment provider to let you the full flexibility of the payment system you want to use. We now integrates [Mollie](https://www.mollie.com/) as a new payment provider, it works the same way as Stripe where we orchestrate your account automatically for you.
With Mollie you can also benefit from credit card and SEPA direct debit capabilities, at a lower price than Stripe.
# Product updates August, 2023
## New checkout page
Our hosted checkout page was revamped to a slicker and clearer structure.
Due dates, subscription, and one-time payment are now more clearly displayed with precise dates and summary.
## Multiple bank accounts
You can now add multiple bank accounts for different currencies.
In addition, we now support new bank account details formats:
* Account Number - (Ach) Routing Number
* Account Number - BIC/Swift
* Sort code - Account Number
* and IBAN - BIC (already supported)
If your customer decides to pay with bank transfer, we’ll pick the right bank account and format to put on the invoice depending on their currency.
## Zapier app
Hyperline now smoothly integrates with Zapier with a dedicated app!
You can sync in a few clicks, without any code, your customers base with your favorite CRM, react to Hyperline events to run workflows on your specific tools, push invoices data to your accounting software, push usage events from your tracking tools, …
The set of possibilities is endless!
*[More details in the documentation](../integrations/zapier)*
## Grace period for usage invoices
When using pricing with items based on usage data from your product, generated invoices now enter in a grace period before being sent for payment.
This period allows you to have a complete control over the final invoices and review them.
During this period, invoices don’t have a number, can be updated/refreshed to ensure accuracy, or manually validated before the end of the period.
The number of days of the grace period can be configure in the settings (default to 3 days).
## React components (beta)
Integrate Hyperline capabilities right into your product with just a few lines of code!
We now provide React components to embed customer’s active subscription and payment method (display + edit).
Generate a token with the API, insert the component with possible customisation, and that’s it. No more complexity!
*[More details in the documentation](../api-reference/docs/react-components)*
# Product updates October, 2023
## New customer page and subscription details
This is our first rollout toward our largest iteration to date in Hyperline: our new subscription model with way more flexibility.
In this improvement, we revamped the customer and subscription details page, using a better page structure and organization of the information. You can benefit from more clarity in the display of the subscription products (including all the *future* parameters, a preview of the evolution of metered pricing depending on the consumption, etc.) and the future invoice.
You can also now zoom in and display the details of a subscription on a dedicated page.
## Better currency management
We've made updates on how we handle currencies in Hyperline, especially when you invoice in multiple currencies, to manage more complexity out of the box for you.
The concept of “main currency” is now replaced by two distinct currency types:
* the **accounting currency**: automatically set by us and depending on your company country. This currency cannot be changed as it's used to maintain your accounting ledger with your country's legal requirements. This only affects the footer of your invoices, where we'll display the converted amount when needed;
* the **reporting currency**: configured by you, used in the dashboard page, and revenue analytics computations.
## **ACH Direct Debit 🇺🇸**
We now support ACH Direct Debit!
Like SEPA Direct Debit, this method allows US companies to set up direct debit payment methods for their customers with a US bank account.
## Forward customer emails
You can now set up in your settings custom emails where we'll forward emails sent to your customers. This allows your finance team, accountant, or anyone else to stay in the loop.
## **New login flow (including login with Google)**
Hyperline's users can now log in or sign up using a password or their Google account!
Additionally, we added a reset password flow, and sign up is directly accessible from this page.
## Third-party app
We now allow external products to integrate Hyperline by orchestrating existing accounts. This enables building third-party integration using OAuth2, and adding/using billing capabilities on top of another product with ease.
*[More details in the documentation](../api-reference/docs/third-party-app)*
# Product updates November, 2023
## Product Catalog
We introduced the concept of **reusable products** in Hyperline, which can be configured in a single catalog, allowing you to define different **prices based on a variety of parameters**, including currency, billing interval, commitment duration, country location, etc.
New pricing types are now available including **basic fee**, **volume-based** pricing, or **BPS-based** pricing, in flat-fee, seat, or usage-based products.
*[More details in the documentation](../docs/products/overview?utm_source=changelog)*
## New plans set up
Defined products can now be **reused in one or multiple plans**, plans act as a template for subscriptions where you can define your different offers.
## Even more flexible subscription model
Your customers can now **have multiple active subscriptions** simultaneously. Additionally, a single subscription can **include products with different billing intervals**, trial periods, and commitment durations.
This allows you to represent a wide range of needs, from simple cases to complex ones, such as “a customer committing for one year with a two-week opt-out trial period, featuring an annual upfront fixed charge and monthly usage consumption”.
The checkout session page, which is used for customers to explicitly subscribe and provide their billing details, is now optional. Additionally, in this new version, we offer greater flexibility in terms of payment options and subscription activation.
Obviously, all this logic can also be orchestrated using our API.
*[More details in the documentation](../docs/subscriptions/create?utm_source=changelog)*
## Invoices exports
Invoice exports are live, no more blockers for your accounting! You can now retrieve in one click your invoice data for the period of your choice including line items and PDF files, in JSON, CSV, or XLSX format.
## General Availability of GoCardless
To extend our payment collection capabilities and our promise to stay agnostic from a payment provider, Hyperline now fully **supports SEPA Direct Debit payment through GoCardless**.
Connect your account in one click, your existing mandates can also be imported!
## Customer payment method settings
You can now **customize payment methods at the customer level**, specifying both the methods you allow and the ones that should be used by default. These choices will be reflected on your customer’s checkout pages and portal.
Furthermore, we now offer the option to **disable the payment collection** logic in Hyperline entirely, allowing you to manage it on your own if you already have a system in place.
## Tailored onboarding flow
Our new customers can now benefit from a dedicated in-product experience to help them set up their accounts. Follow the steps and start billing without stress.
## New documentation portal
We recently invested a significant effort in revamping our [documentation](https://docs.hyperline.co), making it accessible to everyone, including non-tech folks. The technical documentation is now more complete than before, including a detailed API reference.
# Product updates December, 2023
## Enhancements for billing plans
We have enhanced price management for plans, enabling you to **customize the price of a specific product within the context of a plan**. This feature allows you to utilize the same product from your catalog in different contexts while representing all possible pricing variations based on factors such as currency, payment interval, commitment period, country, and now, the specific plan in use. Navigate to your plan and click on the 'Customize Prices' button for the desired product.
Also, you can now see your **revenue breakdown among different plans**. Simply navigate to your [Plans](https://app.hyperline.co/app/plans) page to view this information.
## Email tracking
You now have **visibility into the emails sent by Hyperline and their status as opened** by your customers. Hyperline automatically sends emails for new checkouts and invoices (both to be paid and paid) to your customers.
These emails will now appear in your history section on the invoice or subscription pages with a tag indicating whether they have been **Sent, Delivered, or Opened**. This enhancement will help you maintain complete visibility into the communication process.
## Account manager user role
We've introduced a new user role called 'Account Manager' designed for invited users such as sales teams or customer success teams. This role **only grants permissions to manage customers, subscriptions, and invoices**. Meanwhile, the 'Account Owner' and 'Admin' roles retain access to the entire product, including settings.
*[More details in the documentation](../docs/get-started/configure-account#team-members)*
## Cancel subscription
We revamped our subscription cancellation process to provide you with enhanced flexibility and clarity. You now have the option to choose when a subscription should be canceled—either **immediately or at a specific future date**. We present a **clear balance**, indicating the amount to be paid or reimbursed by your customer. You can then decide to bill and refund your customer with the **pre-computed amount**, opt for a **custom amount**, or choose to **ignore** the payment altogether.
*[More details in the documentation](../docs/subscriptions/manage#cancel-subscription)*
## Snowflake
We have added a new native **Snowflake integration** that enables you to connect your database directly to Hyperline using dataloader. Now, you can effortlessly ingest your usage data with zero dev time!
## Test mode
No need to logout and re-login between your main account and your sandbox (test) account. Both authentication flows are now linked and you can **switch from one mode to another in only one click** using the "Test mode" switch button on the bottom left corner of the product.
*[More details in the documentation](../docs/get-started/sandbox)*
# Product updates January, 2024
## Automated seat-based billing
We have introduced a significant enhancement to the "seats" product in Hyperline, designed for representing licensing where the cost of a software application or service is based on a quantity of items (users, accesses, licenses, etc).
Now, this product can be **seamlessly connected to your usage data using a [dataloader](../docs/usage/usage-data-with-connectors)**. This integration sets it apart from a proper "usage" product, as it incorporates all the business capabilities of a seat product (increase/decrease of a quantity with [volume](../docs/products/overview#volume), [packaged](../docs/products/overview#packaged) or [bulk](../docs/products/overview#bulk) pricing models) while adding specific options to this pricing model, such as prorata calculations, custom refresh frequency, invoicing and application schedules, and refunding decreases—**all achieved without the need for any development time**.
*[More details in the documentation](../docs/usage/connected-seats)*
## Salesforce
This marks our first step into CRM integration. Hyperline now enables you to seamlessly **connect your Salesforce account** for automated data synchronization.
It facilitates a **bidirectional sync** between Hyperline customers and Salesforce accounts. Additionally, we push detailed information about Hyperline subscriptions and invoices to Salesforce, also providing prebuilt URLs for management of them. This allows you to create custom page layouts, flows, or analyses directly within your CRM.
All of this without the need for dev time, manual complex configuration operations, or app installation.
Additionally, we have introduced a **dedicated integrations page in the settings**, providing a centralized place where you can access all the capabilities.
*[More details in the documentation](../integrations/salesforce)*
## Custom properties
To provide you with greater flexibility, we have introduced the ability to define structured custom properties that can be associated with customer, product, plan, and subscription entities. These properties support various types including simple text, number, boolean, date, and a select list with predefined values.
This addition allows for a range of use cases within Hyperline. For instance, you can now manage the SIREN of customers directly within the product as a structured property, store additional context for each main entity managed through the API, or representing a set of features enabled by a specific billing plan.
This capability can be managed either through the user interface or via the API.
## Pennylane
Hyperline now enables you to seamlessly **connect your Pennylane account**.
This allows us to automatically send invoices with their complete details, including line items and PDF files, along with payment details. Moreover, we retrieve payment details from Pennylane, facilitating automatic reconciliation and marking invoices as paid.
*[More details in the documentation](../integrations/pennylane)*
## Provider fees
We now display the total provider fees for each payment directly in Hyperline, for each invoice.
This enhancement provides clear visibility into this often overlooked cost, offering transparency on the deduction imposed by your current payment processor or service.
In this specific example, Stripe takes \$38.57 which represents more than 3% of the card transaction total amount.
## BigQuery
We have added a new native **[BigQuery](https://cloud.google.com/bigquery) integration** that enables you to connect your database directly to Hyperline using dataloader. Now, you can effortlessly ingest your usage data with zero dev time!
*[More details in the documentation](../docs/usage/bigquery)*
## Quick actions
We have added a convenient way for quick access to creating customers, subscriptions, one-time payment invoices, products, plans, or coupons. These options are always accessible in the navigation bar.
# Product updates February, 2024
## Create, edit and duplicate invoices
We've introduced several enhancements to our invoices. You can now [create new invoices from scratch](../docs/invoices/create) or [edit existing draft invoices](../docs/invoices/edit) with a real-time visual rendering. This provides you with complete flexibility and control over your invoice content before finalizing and sending it for payment.
Additionally, you now have the option to **duplicate existing invoices**, copying all major details for a seamless creation process.
## Explore invoice events
You now have the capability to **explore events related to an invoice featuring usage products**. This empowers you to gain a comprehensive understanding of the invoice's composition, providing clear visibility into the contribution of each event to the total invoice amount.
This explore feature is **available on the customer portal** for both past invoices and the upcoming invoice (i.e. the one open for the current billing period).
Furthermore, we provide the option to **download a CSV file** containing all the data for further processing in your preferred external tool.
## HubSpot
Hyperline is now **integrated with HubSpot**! Similar to the Salesforce integration, this feature enables a **bi-directional synchronization** between Hyperline customers and HubSpot companies. Furthermore, we introduce a **HubSpot card** that allows you to assign, manage, and access Hyperline subscriptions directly within your CRM, without the need to navigate away.
A comparable widget capability is now accessible for [Salesforce](../integrations/salesforce/component) as well.
*[More details in the documentation](../integrations/hubspot)*
## Subscriptions page
We have introduced a brand new subscriptions page, which displays a **list of all the subscriptions** of your account. This provides you with clear visibility of your subscriptions in one central place, featuring filtering options and the ability to **export the complete data as a CSV file**.
## Reports and exports
To assist you in conducting more **in-depth financial analyses**, we have implemented a comprehensive report feature. This functionality enables you to **download pre-built files**, such as revenue per product/country/plan, aged balance, outstanding invoices, and more.
While we have plans to introduce additional reports in the future, we welcome your suggestions for new ones. Feel free to share your ideas.
Additionally, you now have the capability to **export your customer list into a CSV file** for external processing. Simply utilize the 'Export customers' button available on the [Customers page](https://app.hyperline.co/app/customers).
## Resend invoice emails
We now provide a feature that enables you to **resend past invoice emails** to your customers, whether it be for invoices that are yet to be paid (serving as a reminder) or for those that have already been paid.
## Add/remove products from subscriptions
You now have the flexibility to add or remove products at any time from ongoing subscriptions. We offer various options for charging the customer on a pro-rata basis, with the full price, and more.
Simply go to your subscription details page, and click on the 'Add product' button in the Products section; or click on an existing subscription product and 'Remove product'.
# Product updates March, 2024
## Invoice reminders
You can now automate your payment reminders and dunning process directly within Hyperline! We offer a complete invoice reminder module that allows you to schedule email reminders before, on, or after the due date with fully customizable sequences, messaging, and cohorts.
This enables you to tailor your wording and email frequency based on your criteria, automating your payment reminders and dunning process, thereby eliminating tedious manual actions and ultimately reducing your outstanding and unpaid invoices.
*[More details in the documentation](../docs/invoices/reminders)*
## Flexible subscription updates
Alongside offering the most flexible subscription model on the market, we now enable you to have full control over your running subscriptions with dedicated update flows. Easily change your subscription's invoicing parameters, dates, purchase orders, or product configurations for live subscriptions without recreating them from scratch.
## Automated invoice reconciliation for SEPA bank transfer
Reconciling your banking transactions with their corresponding invoices for wire transfer payments can quickly become tedious. We are introducing our first step toward eliminating this manual task with an automated invoice reconciliation feature for SEPA bank transfers, powered by Mollie.
We assign a dedicated IBAN (always the same for the customer) and a reference number to the invoice. Then, when a payment is received in the related account, we automatically mark the invoice as paid accordingly.
## E-invoicing compliance
Hyperline is now fully compliant with the European standard for electronic invoicing, especially for countries (like Italy) where the standard is already in place and mandatory.
For France, the standard has been postponed to 2026, but we anticipate this compliance aspect to incorporate it into our product foundations.
*[More details in the documentation](../docs/invoices/einvoicing)*
## View previous invoices version
Related to the invoice edition feature, you can now browse your history to view previous versions of a specific invoice prior to its updates.
## Wallet use for bank transfer invoices
The wallet feature in Hyperline is a useful tool that allows your customers to prepay money to cover future invoices, and enables you to offer specific amounts to be deducted from the next customer invoices.
This capability is now also available for customers paying by bank transfer: the invoice total amount will be deducted from the available customer wallet amount, requiring your customer to only pay the remaining amount.
## More fields supported on CRM integrations
We've added a variety of new fields to be synchronized between Hyperline and your CRM, including customer language, timezone, invoice emails, tax number, custom tax rate, custom payment delay, next payment date, and amount, among others. If you are interested in using them, simply go to your CRM integration page in Hyperline, then use the Actions > Reconfigure button.
*More details in the [Salesforce documentation](../integrations/salesforce) or [HubSpot documentation](../integrations/hubspot)*
# Product updates April, 2024
## Send quotes to your customers
In our mission to simplify all topics related to billing, we are introducing a **new quoting feature native in Hyperline**.
Create a quote containing subscription configuration and details, and send it for signature to your customer. The subscription and invoicing will start automatically with all the agreed price and contract configurations, eliminating the need for additional manual actions in between.
Quotes are also available through Salesforce, HubSpot, and Zapier integrations.
This quote feature is in private beta. We are eager to hear feedback from the first usage, and many new capabilities are planned to come in the coming weeks. Let us know if you are interesting testing!
## Automate invoice reconciliation with Bank Connect
Last month, we announced a new method to streamline the invoice reconciliation process by incorporating generated and unique bank details attached to the invoices, leveraging capabilities from Mollie.
Taking this initiative forward, we are now enabling you to **connect any external bank account** and automatically reconcile transactions received on it with Hyperline invoices!
*[More details in the documentation](../docs/payments/reconciliations#with-an-external-bank-account)*
## Discover our revamped customer portal
Our customer portal (shareable public page) now has a fresh new look!
We've revamped the interface to make it shinier, simpler to read, and easier to understand. It allows the display of multiple subscriptions along with additional details.
## Improved invoice translation
We've improved translation support for products and invoices. You can now **add alternative translations for your product names** (defined in your product catalog). The correct translation will be used on your invoice depending on its language.
Additionally, the Hyperline invoice layout is now available in Dutch.
You can also include custom text notes/messages on the invoice for your customers. This feature is accessible when editing an invoice before sending it for payment.
## Explore live consumption for seat-based product
As for usage-based product, you can now **browse live consumption for connected seat products**. This provides you (and your customers) with a clear understanding of the events taken into account for billing.
## See past subscriptions
We now list all past and canceled subscriptions on each customer, providing you with detailed visibility into their history. Track subscription changes, upsell, downsell, and customer evolution in a single place.
Additionally, you can now add or remove coupons from a live and active subscription.
# Product updates May, 2024
## Public invoice page
**Sharing a link to provide details** to your customer or **receive payment about a specific invoice** is now possible with the public invoice page.
Like checkout, portal, or quote pages, the public invoice page allows you to share a publicly accessible link with your customer, including invoice details, usage consumption history, and a payment form.
*[More details in the documentation](../docs/invoices/invoice-page)*
## Upload extra documents and e-sign quote
As a first iteration following the beta launch last month, we focused on **allowing the attachment of additional PDF documents to the quote**, so you can include detailed contracts, terms of use, conditions, or any other document that makes sense for your business and you want your customer to review as part of their quote signature flow.
Additionally, we added a way to **electronically sign quotes**, making them legally compliant. This flow is backed by Yousign, a leading European signature provider.
## Connect multiple payment providers
You can now **connect multiple payment providers** to your Hyperline account. This allows you to distribute payment method usage among multiple providers at different costs. For example, you can let your customers pay by card using Stripe and by SEPA Direct Debit using Mollie.
## Organisation-based billing
One of the main challenges when implementing invoicing for multiple entities within a single customer group is now a no-brainer with Hyperline! You can **represent parent/child dependencies between customers** and choose how you want invoices to be issued (invoice the parent company, group all child invoices into a single one under the parent, etc.).
*[More details in the documentation](../docs/customers/organisation-based)*
## MySQL dataloader
MySQL is now available as a Hyperline dataloader. Similar to PostgreSQL, MongoDB, BigQuery, and Snowflake, you can pull your usage data for billing with just a few configuration clicks and without complex technical integration.
*[More details in the documentation](../docs/usage/usage-data-with-connectors)*
## Fincome integration
[Fincome](https://www.fincome.co) now natively supports Hyperline. Benefit from all Fincome capabilities to analyze your subscription revenue from your Hyperline data.
## Payment Provider Explorer
A new Hyperline side project we released this month, a powerful comparator of payment providers and associated costs with the [Payment Provider Explorer](https://paymentproviderexplorer.hyperline.co). No more hidden fees!
# Product updates June, 2024
## Invoicing entities
Hyperline now allows you to represent **multiple invoicing entities within the same account**. This feature enables you to issue invoices to your customers from different sellers, such as various invoicing subsidiaries or entities you issue on behalf of.
This capability lets you maintain your entire account configuration (products, plans, settings, ...) while easily issuing invoices from different senders you represent.
The invoicing entity can be customized per customer, allowing full flexibility.
No limit on the number of entities apply, and the feature is accessible both in the interface and through the API.
## Update subscription prices
As the last step of subscription updates, we now allow you to **edit the prices of products that are part of an active subscription**. These changes are tracked in a history trail within the subscription page.
This way, you can apply price changes and upgrade or downgrade a subscription without creating a new one, allowing you to keep track of all changes to a customer contract.
*[More details in the documentation](../docs/subscriptions/update#update-product-prices)*
## Edit members role
Hyperline allows you to invite team members with either an Admin or Account Manager role. You can now **edit the role of an existing user** autonomously in your account settings.
*[More details in the documentation](../docs/get-started/users)*
## Add credit products in plans and subscriptions
Credit products can now be added to predefined billing plans and subscriptions like any other product.
*[More details in the documentation](../docs/credits/overview)*
## Edit extra details on emitted invoices
Sometimes it appears that extra information was missed, but the invoice has already been issued. For legal reasons, the core of the invoice cannot be edited. However, you can now **edit the Purchase Order number and the custom note** attached to the invoice.
## Redirect button on customer portal
We added a feature that allows you to **add a button with a custom label and link on the customer portal**. This way, you can easily redirect customers to your product, add an additional link to an external resource, and more.
## New React components
Following the release of our new portal a few months ago, we upgraded our React components library. Each component now has a fresh new look that matches the latest portal design.
*[More details in the documentation](../api-reference/docs/react-components)*
# Product updates July, 2024
## Quote templates
With the release of quote functionality completing the CPQ process on Hyperline, you can now create **quote templates to streamline the quote creation process**. Say goodbye to copy-pasting contract terms and repeatedly re-uploading the same PDF attachments, you can now simply select an existing template from the gallery and create a quote in just a few clicks.
## Dynamic matrix pricing
Dynamic products with usage are now more powerful than ever. You can now **configure specific pricing based on your own fields** within usage events. This allows you to create complex pricing matrices and price points based on specific usage parameters and values.
For example, if you are selling cloud computing services, you can apply different prices depending on the compute instance type and/or region. Similarly, if you are selling banking transaction processing, you can apply specific fees based on the scheme and/or card configuration.
## Subscription assignation
The second step of the subscription assignment flow has been updated with a fresh look, and simplified and clearer options. You can now directly manage the allowed customer payment methods and choose whether to activate the checkout flow.
Additionally, you can now fully disable checkout capabilities in your account settings if you prefer not to use them.
## Multiple customer payment methods
Hyperline now allows your **customers to store multiple payment methods** on their portal page. Whether they are using different cards or a combination of a card and a direct debit mandate, they can save multiple options. This functionality is also available if you have multiple Payment Service Providers connected.
For example, your customers can add their card using Stripe and set up a SEPA direct debit mandate using GoCardless. This process will be seamless for your customers, who will see only two payment method forms, without being aware of the underlying provider complexity.
## More filters
You can now filter customers, subscriptions, and invoices tables by a specific invoicing entity. Additionally, date filters are now available, allowing you to filter subscriptions based on start or cancellation dates, for example.
# Product updates August, 2024
## Custom tax rate
Hyperline now supports the creation of **custom tax rates by invoicing entity**. These rates can be applied to products in the catalog to customize the tax for each product. The complexity of multiple tax rates is managed across all flows, including checkout, portal, quotes, and invoices, making invoicing processes even easier.
Additionally, you can now configure external 'Product code' for each product in your catalog, which facilitates reconciliation between Hyperline products and those in external systems, such as accounting software.
## Change invoice payment method
The payment method on draft invoices and invoices awaiting payment can now be changed. For example, you can easily switch from card to bank transfer or update the bank account on the invoice.
## Invoices in 🇪🇸 🇵🇹 🇵🇱
Emitted documents (invoices, quotes, custom documents) from Hyperline are **now available in three new languages**: Spanish, Portuguese, and Polish. These additions complement the existing options of French, English, German, Italian, and Dutch.
## Subscription pricing configuration
When assigning a subscription, we have simplified the process of adding and configuring products. You can now select any pricing setup from the product catalog and edit the configuration in a dedicated side panel. This provides greater flexibility when setting products to a subscription and allows for the selection of bundles for credit products.
## Quotes export
Quotes can now be exported to CSV files for external use.
# Product updates September, 2024
## Translations of hosted pages
Hosted pages (checkout, portal, quote, and invoice pages) are now available in all supported languages, including **French, English, German, Italian, Spanish, Portuguese, Dutch, and Polish**. This completes the translation of emitted documents (invoices, quotes, and custom documents) already supported, ensuring that your customers can experience the entire flow in their preferred language.
## New accounting integrations
Hyperline now natively integrates with **[Xero](../integrations/xero)** and **[Exact Online](../integrations/exact-online)**, expanding our existing accounting software support, which already includes Pennylane. Invoices and credit notes are automatically pushed to your accounting system with all details, and payment information is synced, making reconciliation a seamless process.
## User permissions
You can now **create custom roles with specific permissions**, offering fine-grained access control for members based on your needs. Permissions are no longer limited to pre-defined roles, giving you full flexibility.
*[More details in the documentation](../docs/get-started/users#manage-roles)*
## Contracts
We've started to introduce a new module that allows you to **manage contract templates and reusable clauses**. This feature simplifies managing a catalog of contracts, tailored to specific invoicing entities, countries, or languages. You can easily add this content to quotes.
## Map tax rates to custom codes
In order to ease integration with accounting and the addition of [custom tax rates](../docs/invoices/tax-management#custom-tax-rates) last month, Hyperline now support **mapping of default rates to custom codes**. This mapping is automatically pushed to Xero and Exact Online.
*[More details in the documentation](../docs/invoices/tax-management#default-tax-rates)*
## CRM more objects
Hyperline now synchronizes way more data on your [Salesforce](../integrations/salesforce) or [HubSpot](../integrations/hubspot) accounts. Push quotes including line items and coupon details, subscriptions including products and coupon details, and invoices including line items, in only a few clicks!
## More flexibility on invoices
You can now select and **assign products from your catalog when creating one-off invoices**, ensuring the correct link between invoice line items and related products, making revenue recognition simpler.
Additionally, you can now **revert an invoice paid by transfer back to unpaid** with a dedicated button that removes the associated bank transaction.
# Dashboard
The dashboard is the first interface you see when logging in to your Hyperline account. It features key metrics at the top, the list of outstanding invoices as well as the coming subscription renewing for the next 7 days at the bottom. It will give you a quick, effective overview on your business.
## Key metrics
### ARR and MRR
Annual Recurring Revenue (ARR) represents the total annualized revenue that a SaaS company expects to receive from its subscription customers over the course of a year, while MRR represents the total monthly revenue generated from subscriptions.
Keep in mind: tax (VAT) amounts are not included in the calculation of ARR/MRR.
### Revenue last 30 days
This displays the revenue for the last 30 days for both recurring and one-time invoices. Right below is the total revenue since the 1st January of the ongoing year.
### Active subscriptions
This displays the number of active subscriptions for your account. Below is the ARPA (Average Revenue Per Account) that provides insights into the average value derived from each customer.
### Churn
The Churn is the rate at which customers or subscribers discontinue or cancel their subscriptions or services during the current month vs the last month.
Churn is also known as "customer attrition" or "customer turnover".
Retaining existing customers is often more cost-effective than acquiring new ones. If you observe a high Churn on your account, consider implementing strategies to reduce it, like improving customer support, enhancing the product or service, offering loyalty incentives (through [coupons](../coupons/overview) or [free top-up](../wallets/top-up)), and analyzing customer feedback to address pain points.
## Outstanding invoices
We display on the dashboard a list of invoices, filtered to keep the outstanding invoices only. This gives you at a glance the list of invoices that are still awaiting partial or full payment.
You can mark the invoices as 'Paid' or 'Partially paid' from the dashboard directly.
## Subscriptions renewing in the next 7 days
This section shows the list of customer subscriptions renewing in the next 7 days so you can view near future activity.
# Reports
Hyperline offers a complete set of pre-built report files, where you can get a clear view of company performance. This will be able to explore a comprehensive range of analysis designed to empower finance teams in making informed decisions or do deeper analysis into their preferred external tools.
The reports are accessible through the dedicated Reports page within the Hyperline platform.
## Available reports
Hyperline offers a curated selection of reports (as depicted in the screenshot above), important for assessing various aspects of your company's financial health, all of which are downloadable as CSV files for convenient access to the data you need at any time.
## Requesting a custom report
If you find that a specific report you require is not currently available, simply click on the 'Ask for a custom report' button. Our dedicated support team is committed to providing you with the tailored data essential for your financial analysis.
# Create & apply coupons
## Coupons definition
Coupons in Hyperline are a way to offer discounts to your customers.
Coupons can be offered as a fixed amount or a percentage of a given price.
Then fill-up the following information:
* **Name**: the coupon's name (try to use simple, clear names)
* **Description**: the description is for internal use only and is not required to create a coupon
* Choose if you want to create a **fixed amount or a percentage** discount
* Choose **the amount or the value** of the coupon
* **Redemption deadline**: set up a deadline if you want your coupon to become invalid after a specific date
* **Redemption limit**: set up a limit if you want your coupon to be used only a specific amount of times
Click on **Create new coupon** once you are done.
Your new coupon will appear instantly.
## Apply coupons
Once you created coupons, you can apply them to customers.
To do so, go to **Customer,** then to **Subscription**, and click on **Assign new subscription.** In the process, you can add coupons.
If you don't have all the information now, you can still create the customer and come back later to edit its details. Only a name is required at this step, but we recommend filling in at least the currency and country of the customer.
You can click on your customer's name from the previous screen to access their information.
From this page, you get an overview of your customer's information on the left of the screen, and you can navigate through their [subscriptions](../subscriptions/manage), [wallet](../wallets/overview), [invoices](../invoices/overview) and events on the right.
After clicking the export button, your customer data will be compiled into a CSV file. Download the file to access a complete export, including customer details, their number of active subscriptions, estimated ARR, and more.
You'll be prompted to choose a parent organisation and then to select an invoicing configuration.
3 options are available at this stage.
* `Individual invoices` will move every invoice for the current customer to the parent and invoice it under the parent configuration while keeping the content identical.
* `Grouped` will set the current customers invoices as pending and concatenate them regularly with other children from the parent. Concatenated invoices will display one line item per children invoice with the original line items listed in description.
* `No change` will attach the child to the parent but will not change any invoicing parameter.
If you have chosen `Grouped` for the child invoicing configuration, you'll need to set the grouping schedule on the parent.
To do this, go to the parent customer page, click on the dots next to "Org. based billing" and select "Children settings".
You'll be able to select a schedule (monthly, quarterly or yearly) and the next invoicing date. From there everything will be automated, but you can adjust the next invoicing date at any time.
As well as displaying information correctly, this portal offers a number of action options for your customers:
#### View subscription details
Customers can access the full details of their subscription by clicking on 'Subscription details' on the portal.
This sub-page will display the content of the next invoice that will be billed, as well as the detailed price structure of every product.
#### Change payment method
To do that, they just have to click on the trash button next to their payment and add the new payment method they want to use.
#### Top-up wallet
You can make your customers autonomous by offering them to top-up their wallet in the portal. For this, make sure you enable the option on the wallet settings first.
Clicking on Top-up wallet on this screen will trigger an immediate payment from the registered credit card and credit the wallets instantly.
#### Edit billing information
To make changes, they simply need to click on the "Edit" option. This grants them the ability to update and modify their billing details as needed, ensuring accuracy and up-to-date information for a seamless payment process.
#### Download invoices
All invoices are listed and can be open to their dedicated [invoice page](../invoices/invoice-page).
Customer can download their invoice PDF using the 'Download' button on the top-right corner.
## How to access the customer portal
To view the portal for a specific customer: go to the customer page, select the customer you want to view then click on the 'Portal' button.
You can easily provide your customers with this unique portal link. Each customer portal link is individually generated and secured through a unique ID.
## Customize the portal
### Colors & brand identity
The portal adopts the primary brand color and icon that have been configured in the 'Settings' section under the 'General' tab of Hyperline. This uses the same codes as those displayed on the invoice sent to your customers. This feature enables you to personalize your customer portal with the distinct colors and branding of your company
### Set a custom domain
In order to personalize further the experience for your customers, you can configure a custom domain for the hosted portal and checkout pages.
You can set it in [your settings](https://app.hyperline.co/app/settings/hosted-pages), and to enable it you need to add a `CNAME` record pointing to `cname.hyperline.co` on your DNS provider.
For example: you want to set your custom domain to `billing.alpeak.com` in Hyperline, and add the related `CNAME` record on your DNS provider, we will provide you portal and checkout URLs with the form:
```
https://billing.alpeak.com/portal/:customerId
https://billing.alpeak.com/checkout/:sessionId
```
We will automatically manage the related HTTPS SSL certificate.
# Configure your account
## General configuration
### Company information
You will be asked to fill up the following information about your company:
1. Your company's trade name (the name used to conduct your business)
2. The company's email address (for invoicing inquiries)
### Brand identity
You can also brand your invoices with one color and your company's logo. We provide you with a real time preview on the right of the screen so you can see how your changes are affecting your invoices design.
### Billing information
This section impacts the footer of the invoices. You can add here:
1. Your company's VAT number (make sure the number is valid. A warning icon will appear if it is not)
2. The company's legal name (that can be different from the trade's name)
3. The company's address
When you're done you can click on **Save changes**.
## Payment
This is done in the **Payment** section. To get started with Hyperline, you will need to provide means of payments (connecting with your PSPs and/or adding bank accounts) and choose which payment methods you want to accept from your customers.
### Connect your Payment Service Provider
Hyperline currently supports three major Payment Service Provider: **Stripe**, **Mollie** and **GoCardless**. If you already have an account with one of those, you can connect it in one click without any technical requirement (no API key, no webhook to connect, etc.).
1. Click on the **Connect** button for the PSP of your choice. This will redirect you to the PSP login page.
2. Enter your account credentials and click on **Continue.**
3. Once the process is completed, you will see the PSP status change to `Active` in Hyperline.
When connected, we will automatically orchestrate your account for you (create, update, refund).
### Add your bank accounts
If you intend to accept bank transfers from your customers, you can add one (or several) bank account(s) by clicking on **Add a bank account**. This is the account that will be indicated on your invoices **depending on the currency of the invoice** when your customers decide to pay by bank transfer.
1. Fill-up the **country**, **currency** and **name of your bank**
2. Select the bank account format and enter the details
3. Click on **Add bank account**.
You will see your account appear in the list. You can delete it anytime by clicking the three-dot menu, and **Delete**. Deleting your bank account information will disable (if you had only one) the bank transfer payment method until you add a new bank account.
You can add a bank account with various formats to accommodate different countries and currencies. These formats include:
1. IBAN / BIC/Swift (for countries in the SEPA area, primarily European)
2. Account Number / (Ach) Routing Number (US - USD)
3. Sort code / Account Number (UK - GBP)
4. Account Number / BIC/Swift (all other cases)
Invoices will display the correct format when customers opt to make payments via bank transfer.
## Accounting currency
In most countries, you're legally required to maintain your accounting ledger in your country's main currency. This can get tricky when you're invoicing customers in multiple currencies. At Hyperline, we're setting your accounting currency to your invoicing entity country currency to make sure you won't have any legal issue down the road.
### Support email
Hyperline uses a designated email address for support-related communication.
This email is used when issues are detected with your integration, data loaders, or API. By providing a specific email for these notifications, you can ensure that important updates regarding your system's status are directed to the appropriate channel.
### Customers automated emails
Hyperline allows you to manage the types of emails sent to your customers. There are 5 different types of emails that can be enabled or disabled according to your preferences.
* Invoice to pay
* Invoice paid
* Checkout session created
* Checkout session completed
* Payment error
Click on 'Save changes' to validate.
This settings apply to all your customers.
You have the ability to independently [manage your team members](./users) for each account, allowing for precise control over access permissions.
# Testing mode
Learn how you can experiment with billing safely before going to production
## Hyperline test mode
We are well aware that setting up a billing platform can be stressful or intimidating at first glance, especially because it requires experimentation and is linked to an important aspect of your business: revenue. This is why we provide you with a **test mode** (also called **sandbox**) to conduct all kinds of tests without impacting your real account.
When switching to the test mode, this will allow you to perform fake transactions, generate false invoices, add fake customer accounts, and so on. You can get some experience with our features before setting up your real account.
This mode offers the **exact same features and works the same way as your Hyperline (real) account**. Please refer to this documentation to learn how to configure your [product catalog](../products/overview), manage [pricing plans](../plans/overview), [send invoices](../invoices/overview), [use credits and wallets](../wallets/top-up), and more.
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.
## Invite members
By default, two roles are created 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)
Additionally, you can for example create roles for external accountants, finance team, product/tech teams, sales representatives, etc.
### Create new role
It's a complex process with many possibilities, and 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 and when you're building your 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 and gain 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, businesses can streamline their billing processes, maintain strong customer relationships, and continue on the path to growth and success.
You want to learn more about this topic? [Read our blog article](https://www.hyperline.co/resources/blog/billing-simplified).
# Invoice configuration
How to configure your invoices
If you did not already configure your invoices during the initial onboarding process, you can do it anytime from the 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 are also required to fill up the trade and legal names of your country, your Tax number (if applicable), and the postal address that will appear on the invoices. These details are required to make your invoices legally compliant.
Click on `Save changes` once you are done.
## Invoicing
You can customize settings that will apply to all generated invoices. New configuration will be applied for invoices generated after the changes will be saved.
#### Invoicing number
You can customize how your invoices will be numbered. This is done in **Settings**, in the **Invoicing** section.
#### 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. The relevant language will be automatically selected when the invoice is generated.
Click on `Save changes` when you are ready.
# Create invoice manually
Learn how to create an invoice manually
In most cases, invoices are automatically generated, either on a recurring basis for ongoing subscriptions or from one-time payments.
Hyperline also enables **manual creation of invoices for specific ad-hoc needs** with a visual preview. To do this, click on the 'Create Invoice' button from the customer details page.
## Invoice header
#### Emission date
For legal reasons, the emission date cannot be updated and will be set on today's date.
#### Due date
You can set the due date anytime in the future, including today. This will function the same way as the payment delay: once the due date reached, the invoice status will change to late.
#### Purchase order
Optionally, you can add a custom purchase order on the invoice.
#### Custom note
Optionally, you can add a custom note on the invoice. You can use it to add any additional information to your customer.
## Line items
Line items correspond to the products on your subscription and one-time-payment invoices, expect they are fully custom, and not connected to the product and coupons catalog. This means you can add custom line items and coupons that will be one-use only.
#### Add line item
You can add an unlimited amount of line items to your invoice by clicking on new line item. The name, description and display a custom payment interval can be fully customized. The quantity and unit price will be multiplied automatically to calculate the total price. The VAT rate is set based on the customer country, and cannot be edited.
#### Delete line item
Line items can be deleted at any moment by clicking on delete line item.
## Coupons
Coupons will apply a discount to the total amount of the invoice before taxes.
#### Add coupon
You can add a coupon and customise its name and discount amount.
#### Delete coupon
Coupons can be deleted at any moment by clicking on delete coupon.
## Create draft invoice
Once all set, you can click on 'Create draft invoice'.
The invoice generated will not be sent to the customer, but put into a `draft` status. You will be able to [edit the invoice](./edit) as many times as a needed before generating the final invoice to send it to your customer.
# Custom documents
How to customize your custom documents
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.
# Invoice emails
Overview about customer email notifications for invoices
Hyperline automatically sends invoices to your customers via email.
The recipient email corresponds to the one specified in the **Invoice emails** field on your customer page (located in the Information panel), or, if not defined, to the main **Email** of the customer.
## Invoice ready to be paid
When a new invoice is issued and the customer chose to pay manually by bank transfer (during his checkout), we will automatically send this email with the PDF attached.
We attach automatically on the invoice the bank account details you configured in your Settings > Payment page (bank account corresponding to the currency of the invoice).
## Resend an invoice or credit note by email
You can resend an invoice or credit note by email by clicking on the **Resend by Email** button in the invoice dropdown anywhere on the site either on the [invoices list](https://app.hyperline.co/app/invoices/list) or the invoice page
It will send the right email according to the status of the invoice.
You'll be asked to confirm the action and reminded of the email it's going to be sent to. Note that invoice email will take precedence over the customer's email.
If everything looks good, press "Resend email", and the email will be sent. An entry will also be added to the invoice's history.
# Invoice exports
Learn how to export your invoices
If you wish to export your invoice data, especially for accounting purposes, Hyperline provides you with built-in and flexible file exports.
## Export flow
## 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, the invoice will be displayed and can be downloaded 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 into a CSV file by clicking the button on the top-right corner.
# Overview
Overview of the invoice concept
## 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.
Invoices are managed in the **Invoices** section of Hyperline. You can [configure your invoice](./configuration) in the Settings pages.
### Invoice's payment method
The customer's default payment method is used when creating an invoice. While an invoice is not paid, you can update it.
### Invoice's 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 language
Hyperline invoices are currently available in **English, French, German, Italian, Spanish, Polish, Portuguese and Dutch** languages.
The invoice is generated 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 status
* **Draft** - Represents an editable invoice. We are only using 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, we create an open invoice (generated without a number) in the background that we update on a regular basis 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. Invoices attached to an automated payment method will be automatically charged. Invoices paid by bank transfer will remain with this status until [you mark them as paid](../payments/reconciliations).
* **Partially paid** - The invoice has been paid only partially (only for transfers). See the [Transactions & reconciliation page](../payments/reconciliations) for more details.
* **Paid** - The invoice is fully paid and now has a settled date, you can bookkeep it.
* **Missing payment info** - We haven't tried to process the invoice because the related customer doesn't have a payment method.
* **Error** - We have tried to charge the invoice 4 times (3 retries) and it failed. Learn more on how to handle payment errors [on this page](../payments/payment-errors).
### Invoice categories
* **Refund** - The related payment has been refunded. A credit note has been issued.
* **One-time payment** - Describes a one-off invoice.
* **Subscription** - Describes an invoice that is part of a subscription.
### Invoice filters
* **Outstanding** - Invoices that have been only partially paid and still awaiting for payments.
* **Late** - Invoices with passed 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 on the **Invoices** tab.
## Send recurring invoices
Recurring invoices are automatically generated for recurrent payments, such as for monthly subscriptions. For this, you need to [assign](../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-off invoices (charge one-time payments)
One-off invoices will be generated for one-time payments, such as onboarding fees, unique license fees or any other kind of product with a **fee** model you create from the **Product catalog** section.
To charge a one-time payment:
1. If you select **Charge immediately**, the invoice is created instantly and will appear with a **Paid** status.
2. If you select **Generate checkout link**, an invoice will be created with a **Draft** status until the customer pays through their checkout page.
As an alternative, you can [provide a free top-up on your customer's wallet](/docs/wallets/top-up), which will be used to pay for future invoices.
## Visualize your credit notes
To see your credit notes:
From there, you can download credits notes and/or see transactions on PSPs by clicking on the three-dots menu for each credit note.
## Configuring a reminder sequence
To create a new reminder sequence:
The PDF invoice will be automatically attached in all email reminder sent.
To preview the email, you can use the 'Send test email' button.
## Opt-out a customer from reminders
To exclude a specific customer from reminder sequences, you can switch off the 'Invoice email reminders' setting on your customer: go to the Customers page > Click on the customer > 'Edit' link > Switch off the 'Invoice email reminders'.
## Track emails sent
When an email reminder is sent for a specific invoice, a corresponding history log in added to the invoice (invoice details page).
As for other emails, we provide delivery, open, and read status for complete traceability.
# Tax management
Taxes computation can drive a lot of complexity into your invoicing process. Luckily, Hyperline can manage this for you, at no extra cost.
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, it's crucial to determine whether your customers are businesses or consumers. Hyperline will verify VAT numbers for you so you can make sure to only manage legally registered businesses.
Here's a flow chart representing how VAT should be applied (and how Hyperline works under the hood).
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.
### Outside the EU
If you're a business registered within a 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, and rates are usually set by states or local governments and vary significantly across jurisdictions.
## Taxes in Hyperline
In Hyperline, tax settings are managed per invoicing entities, allowing 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 tax standard 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, etc). The correct VAT amount and rate will be applied on the issued invoices.
2. **Manual tax handling**: Hyperline allows manual tax handling where you are responsible for filling taxes by country.
To opt for this mode, you need to navigate to the 'Settings' section, then '% Taxes' and deselect the 'Enable Automated Tax Collection' toggle, which is enabled by default.
### Tax 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 lines.
### Tax per customer
You can customize the tax rate per customer if necessary, but be careful, a manual tax rate set on a customer will not allow Hyperline to display any legal information associated to that rate in the invoice. You can add a custom invoice note for the customer to fix this.
#### Customize tax rate per customer
### Default tax rates
When using the Hyperline's automatic tax collection feature, you can define codes for the default tax rates, so that they match the codes in your accounting software.
#### Assign code to default tax rates
#### Create reusable custom tax rate
# Invoice payment term
Learn about invoices payment term settings
Setting payment term will mark the invoices as **late** once the delay is passed. Choose a number of days that fits your industry's standard or your company preferences.
A default payment delay of **30 days** has been configured in your settings (**Settings** → **Invoicing** page), which can be changed to your preferred value. This payment delay is applied to all your customers.
#### Customization per customer
In the Advanced section, you can enter the custom payment term negotiated with your customer.
This settings can be updated afterward using the 'Edit customer' action, and will impact every invoice created afterwards.
## Grace period
For invoices with dynamic products, Hyperline uses a grace period - defined by a number of days - to **leave invoices open** before being sent to payment. This period allows you to review the invoices before they are finalised.
At the end of this period, invoices are automatically sent for payment.
The default duration is 3 days, but this can be configured on the **Settings** → **Invoicing** page.
#### Behavior during the period
During this period, newly ingested events for the invoice billing period are considered and invoices are regularly updated, so they have the latest accurate usage data.
Invoices in grace period don't have a unique number (not part of the sequential numbering), this number is generated when the invoice is finalized/ready to be paid.
If the new payment is successful, the invoice will now be paid and the subscription will automatically switch back to the live state if the customer is still in the period of the subscription
Additionally, you can optionally configure the **default payment method** used by your customer between the saved payment method, bank transfer, or outside of Hyperline. If not configured, Hyperline will automatically use the first payment method set by the customer.
## Manage payments outside of Hyperline
If you are not interested in using built-in payment capabilities, Hyperline lets you manage payments outside of its system. This is particularly useful if you already have a complex banking system in place or if you are already acting as a payment operator.
For this, you don't need to connect a PSP and you can configure your customers to use the "Outside of Hyperline" option as payment method. When activated, this option will disable all payment-related logic in the billing flows and remove the payment method sections in the checkout and portal pages.
# Transactions and reconciliation
Alongside pricing and billing-related capabilities (including subscriptions, invoicing, etc.), Hyperline assists you with the payment process by charging the payment method and automatically reconciling it.
Payments correspond to the 'Transaction' concept and represent a move of money.
## Transaction status
In the Invoice section, there is a segment dedicated to displaying the invoice's transaction status. This status can be:
* `To process`: The transaction is waiting to be processed by Hyperline system.
* `Pending`: The transaction has been authorized by the related payment processor, but the banking transaction is not yet settled.
* `Settled`: The transaction has been cleared on the banking side, the money transfer is fully completed.
* `Cancelled`: The transaction has been cancelled and won't be processed again.
* `Failed`: The transaction failed. Learn how to handle payment errors [on this page](./payment-errors).
## Payment reconciliation
### With a payment provider
If you choose **cards or direct debit**, invoices processing will be automatic and **automatically reconcile** without the need of manual action.
### With automated bank transfer
Hyperline offers a method to **automate bank transfer reconciliation** by assigning bank account details to each invoice for a customer (the account details remain constant for each customer) and a distinct reference for every invoice.
The bank account details and reference are added to the invoice **when it is ready to be paid** and sent for payment.
When a payment is received in this bank account 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 and unrecognized reference, the funds are returned to the customer's bank account.
When the customer clicks on **Pay**, they will access a link to download their invoice as a PDF document.
From there, the invoice will appear to you in the **Invoices** section as **To pay**.
It will be your prerogative to mark it as **Paid** or **Partially paid** from Hyperline.
#### Marking invoices as paid or partially paid
There are two ways you can switch a **To pay** status to **Paid** or **Partially paid**.
From the Invoices page, by clicking on the three-dots menu on the line of the chosen invoice, and by clicking on **Mark as paid / partially paid**.
Or from the invoice page itself, by clicking on Actions and then on **Mark as paid / partially paid.**
You can choose to mark the invoice as **Paid** or **Partially paid**. Specify the amount paid and click on **Save**.
The invoice status will switch to either **Paid** or **Partially paid**, and the transaction status will be marked as **Settled** which means the transaction has been completed.
Here is how it will look for a partially paid invoice:
And for a fully paid invoice:
# Manage plans
Create plans to make it easier to assign subscriptions
In Hyperline, a plan is **a set of products and preconfigured prices and options**. They are used to represent your pricing offering or the different packages in a more structured way with customer-facing names.
Plans are a way to start a subscription easily, allowing you to start from the preconfigured ones when assigning a subscription to a customer — see them as templates for subscriptions.
A plan can contain multiple products, each product with their own configuration.
You can also configure a specific **commitment period** for a plan, alongside a **trial period**. You can choose to delay the first payment for the subscription to the end of the trial period using the **Delay first payment until the end of the trial period** option.
Note that you can only edit the prices from the price book section. The rest of the product information is for reference only.
## Assign a price book to a customer
If a customer is assigned a specific price book, its prices will be used by default when creating a subscription or quote for them.
You will see the price book used for the product in the subscription details.
# Metering options
Learn about metering in Hyperline
Metered products are a bit more complex than standard products but don't worry, it's still easy to setup.
A metered product is a product for which price is calculated at the end of a billing period based on the data provided through our events system. To know more about ingesting and managing events, you can read our [dedicated article](../usage/send-your-usage-data).
Metering is especially useful when your pricing depends on an unpredictable and variable usage, if everything is committed upfront or not depending on usage data, you should check out our seat-based options instead.
## Pricing configuration
The understand how our different prices models work, you can refer to our [pricing models glossary](../products/overview#pricing-models).
As for any other products, metered prices can be overriden on a per-customer basis directly in the product dropdown.
When you override a price, it's only applied to your current subscription and will be later noted on the customer page.
### Min, max and committed amounts
You can add safety tresholds to your subscription to make sure your customer won't pay under or above a certain price.
Minimum and maximum amounts are applied on prices and we'll show the correct usage as well as the capped/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 treshold value, we'll show 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 4 different metering periodicity which should cover most use cases, don't hestitate 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 straightfoward option for most use cases, like billing overheads for a given subscription period or standard usage-based pricings.
For example, on 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, we'll take into account all events with a timestamp between these dates.
#### Option 2 : Committed 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 treshold (for instance your customer is allowed 10M€ of spent every year with additional usage billed monthly).
For example, on a subscription committed yearly from Jan 2023 to Jan 2024, we'll take into account all events within that timeframe.
#### Option 3 : 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 our 10M€ example, if you want to bill the additional revenue every month you don't want to re-bill previously billed revenue. When this option is selected, Hyperline will take into account the total usage billed the last month and subtract it from the current period usage.
# Products catalog
Learn about product types and pricing in Hyperline
In Hyperline, a product represents anything you sell to your customers. This can be a software, a capability, a service, etc.
These products are managed in a **products catalog**, an interface allowing you to have a complete overview of your offering and manage in a single place the associated and reusable prices based on various parameters (currency, location, market, interval, duration, etc).
Setting up products enables the creation of pre-configured plans, subscriptions, or one-time payments for your customers.
## Types of product
Hyperline enables you to represent a variety of products for sale by leveraging three product categories.
### Fee
A "flat fee product" refers to a product or service for which the cost is a **fixed**, a **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 period where the cost may fluctuate based on factors like usage, consumption, or time.
This product can be used 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.
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 is based on a number of items also named "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 their requirements.
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.
This type of product is related to usage data measured using `events` representing specific occurrences or happenings that needs to be billed during a specific period. Detailed usage reports are also provided, 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
For a usage-based product, metering needs to be configured using operations (such as count or sum) on events to retrieve eligible data, which will be aggregated for billing within the period. Additional filters can be applied to extra fields in each ingested event to narrow down the eligible events for this product. These extra fields can contain custom values (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.
***
## Pricing models
Products in Hyperline support a variety of pricing models: **flat fee** pricing, **volume** pricing, **bulk** pricing, and **basic point (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, depending on the specific characteristics of the markets you operate in, or how you wish to adjust pricing based on 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, or 2200€ per year except for customers committed 2 years where the price is reduced to 2000€ per year.
### 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 is billed 50€ per unit between 0 and 10 then 40€ per unit between 10 and 50, then 20€ per unit, so 2360€ for 63 units.
We offer you a preview of the price evolution depending on the quantity which can help you have an overview of the trend a price can have; and a preview of the rendering of the price for your customer (e.g. on their checkout page).
#### Pay tier in full
The "Pay tier in full" option can be activated 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
As per a volume pricing, a packaged pricing 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. so 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 is billed 50€ per unit if less than or equal to 10 or 30€ per unit if more than 10, so 1020 for 34 units.
As with volume pricing, the "Pay tier in full" is also available, and we offer an overview of the price evolution and final rendering on the customer's checkout page.
### 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). Tiers can be defined to vary this percentage.
As with volume pricing, the "Pay tier in full" is also available, and we offer an overview of the price evolution and final rendering on the customer's checkout page.
## Translating product names
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 on the globe icon.
Once saved, we will update the portal, checkout and new invoices will use the translations when appropriate.
### Hosted pages rules
On hosted pages, the translations being used are, by order of priority:
* Customer's browser's language (if the customer has defined italian as its primary language, that's what we will use)
* Customer's language set on Hyperline
* Customer's country (if the customer's address is in Italy, we'll use italian's translations)
* English
* Default product name
# Custom properties
Learn how to adapt Hyperline to your extra needs using custom properties
Flexibility and customization are key aspects we aim to provide in Hyperline. To achieve this, we allow you to define custom properties so that you can represent and store all the extra data you need.
Custom properties can be defined and associated with **customer**, **product**, **plan**, and **subscription** entities. Furthermore, values are structured with a range of types including **text, number, boolean, date, and a select list** of predefined values.
### Use cases
Custom properties provide a wide range of possibilities. For example, they can be used to represent additional fields for your customers, integrate extra billing details into your plans, assist in entitlement and feature flagging by representing features activatable on specific products or subscriptions. These are just examples, and they can be customized to meet any specific needs based on your use case.
## Create a custom property
You will ask to enter a name, a slug (a unique identifier mainly used for technical integration using the API), the property type, and the entities on which the custom property will be available.
Additionally, you can decide to activate this custom property only for technical purpose, meaning that it won't appear in the Hyperline's interface but will only be available through the API.
When this option is untoggled, the field is both accessible in the interface and the API.
For **products** and **plans**, they will appear in a dedicated box on the product/plan in the 'Advanced settings' section.
For **subscription**, you can set the value in the second step of the subscription assignation flow.
## Displaying custom properties on hosted pages
For now it is only available for the **customer** portal page.
You can decide to 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/get-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), [plan](../../api-reference/endpoints/plans/get-plan).
### How this differ from the `properties` field on customer and subscription
The properties field was introduced in the initial step, but it lacks structure (e.g., it is not named or typed) and is not manageable through the interface for non-technical users.
While this field can still be utilized to store unstructured technical details on those entities, we recommend using custom properties when possible to ensure safety and better manageability.
# Quotes
Learn about Hyperline quoting module
Hyperline provides a complete **CPQ (Configure Price Quote) process**, allowing salespeople to configure products, determine the price (pre-configured or custom) and produce a quote document for signature.
These documents give potential buyers the cost of goods or services before making a purchase decision and facilitate internal purchase approval processes. Once a quote is accepted and signed, the related subscription is automatically activated, starting the billing and invoicing cycle without any additional operations or manual actions.
## Create quote
A quote can be created and saved as draft to be finish later. You can create multiple quotes for a same customer.
*/}
Select a customer for which you want to create the quote.
You can also decide to **collect customer payment details** as part of the quote signature flow. This is particularly useful when your customer pays by card or direct debit, as you can retrieve the payment method mandate and start invoicing with all the required details.
You can also opt to require a **Tax ID** (e.g., VAT number) from your customers. If enabled, providing a Tax ID becomes mandatory for customers to sign the quote.
Additionally, you can require your customer to fill specific pre-configured custom properties during the quote signature flow. This is useful if you have custom needs and you want to retrieve non-standard details from your customer. See more details in the [custom properties page](../properties/overview).
This is particularly powerful because once the quote is signed, the related subscription will start with all the given configurations without manual or technical work in between. Additionally, this ensures that quotes are created only for supported invoicing cases, and the customer will sign exactly what will be invoiced later, without any configuration drift.
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
Learn about Hyperline quote signature process
Hyperline offers natively 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
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
This option allows your customer to sign the quote with probative value.
It uses a secure electronic signature solution compliant with the requirements of Regulation 910/2014 of the European Parliament and Council on electronic identification and trust services for electronic transactions in the internal market (eIDAS).
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 signed, an audit trail document is available on your quote details page, providing proof of the legal signature's validity in case of any event such as a customer dispute.
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.
# Quote templates
Learn how to configure quote templates
To simplify the quote creation process, Hyperline offers a feature to create templates, allowing you to pre-configure quote details.
## Create templates
## Stats
For each template, Hyperline highlights the number of quotes using the template and the related total estimated value.
# Public checkout page
Learn about the hosted checkout page to let your customers subscribe
When assigning a subscription or charging a one-time payment, Hyperline offers the option to create a **Checkout Session**. This generates a public page that can be shared with the customer, where they can view pricing details, enter their billing information, and add their payment method.
## Subscriptions checkout
When assigning a subscription, you can select an option on page 2 to create a new **Checkout Session** for the subscription.
The "send link by email" option will send an email to the customer with a link to the checkout session and can be used to speed up the process, otherwise the link will be available on their Hyperline page.
Payment methods are configured for the subscription whether or not you're setting up a checkout session - but the configuration will be used to choose which form we'll show the customer within the session.
For instance for a subscription with both **Card** and **SEPA Direct Debit Enabled**, you'll get the following interface.
Once the user validates the checkout, they'll receive an email confirming their subscription and the subscription will show as "Active" on your dashboard?
## One-time payment checkout
When charging a one time payment, you can also create a checkout session for the user to purchase your product. Options are the same, the interface looks slightly different as you don't have the subscription parameters.
# Subscription basic setup
Assign subscriptions to customers in Hyperline
Creating subscriptions is a central capability in Hyperline. In this article, we will explore 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 and, optionally create [plans](../plans/overview) to streamline the subscription assignment process, using reusable package configurations.
You can also create new subscriptions from the subscription list page. In this case, you will have to select the customer.
**Subscription start**
* **In the past**, if you want to backport a subscription that has already started but not in Hyperline yet for example - but be careful as we will bill any past period that's due.
* **Immediately**, the default value
* **In the future**, if you want to schedule a subscription for the future
**Subscription alignment**
If the subscription starts on the **first day of the payment interval**, it will be automatically aliged to finish at the end of the payment interval.
Example: my subscription is billed monthly. If my subscription starts on March 1st, the billing period will finish on March 31st ; the next one will start on April 1st, and end on April 30th, taking into account the number of days in the month.
If the subscription starts on **any other day of the payment interval**, the next payment date will be on the anniversary date.
Example: my subscription is billed annually. If my subscription starts on March 14th, 2024, the billing period will finish on March 14th, 2025 and so on.
**Subscription end**
* **End at a fixed date**
* **Keep on running forever**
In the contract configuration, we allow you to configure a **commitment period** during which you want your client to commit, and/or a date until which the subscription is in **trial period**.
If a trial date is configured, the first payment of the subscription can be delayed until the end of this period. This allows you, for example, to enable experimentation time of your tool to your customers, giving them the option to cancel the subscription if they are not satisfied with the service before paying something.
If a plan is selected, these configurations are automatically prefilled.
Select, remove, adjust the products either prefilled from a selected plan or from scratch.
Additional settings are available depending on the type of product (fee, seat, usage).
* **Suggested:** will list the best pricing according to various parameter of the subscription: The customer's country, their currency, the commitment duration.
* **Others:** will list 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" and you can get to the next step where you will be able to enter the price and frequency by yourself.
Once the pricing congifiguration is selected, you can edit the product details.
You also have the ability to assign [coupons](../coupons/overview) to your subscription. These coupons can be a fixed amount in the customers' currency, or a percentage of the product price. They can apply to specific or all products.
**Purchase order**
Add a text element that will be present on the header of every invoice emmitted by this subscription
**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 an invoice is generated, it will be set as a draft that you can edit, finalize and then send to your customer.
**Generate documents instead of invoices**
When Hyperline generates documents instead of invoices,the documents have no legal value compared to invoices and can be used for reporting. You can chose to add VAT to the document or not and set a custom name for the document.
**Do not charge subscription**
The invoices will be created and the invoice will be marked as paid, however, the platform won't charge for the invoices. It's handy for adding subscriptions to your reporting when payment is handled elsewhere.
#### Payment methods
On this section, you are shown the default payment method (the one that will be used for charging the invoices), and the allowed payment methods (the ones the customer can add during checkout and on its portal).
You can edit the customer's default payment method and toggle on or off the allowed ones. These changes will be applied on the customer level.
#### Checkout session
Hyperline provides a hosted checkout page for your customers, allowing 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.
Additionally, we provide you a way to add an email address so Hyperline can **automatically send the related checkout page link** to your customer, without any action from your side.
#### Activation
Three options are also offered to activate the subscription.
* **Immediately** or **Starting on...**, the subscription will start either immediately or on the specified starting date.
* **Manually later**, the subscription must be activated manually on the customer page.
* **After checkout**, this option is only available if you decide to generate a checkout session. The subscription will be automatically activated if the starting date has passed when the customer completes the checkout session. If the starting date is later than the checkout completion date, the subscription will be automatically activated on the starting date.
When activated and started, the first invoice will be automatically sent to the customer depending on the products charged or that need to be paid (more details about [invoice emails](../invoices/emails)).
#### Assign the subscription
When everything is set and ready to go, you can click on **Assign subscription**. If the customer is going to be charged immediately, you will be reminded with a message that will 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
```
Additonnaly, 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 [get subscriptions endpoint](../../api-reference/endpoints/subscriptions/get-subscriptions).
### Create a subscription from a plan
In this example, we create a new subscription from the plan `plan_zHmjoDea4ZRmQV` for the customer `cus_3PYD5R2q5NFK5E`, with a starting date on December 12, 2023 and activated by the customer through a generated checkout session sent by email.
```sh
curl --request POST \
--url https://api.hyperline.co/v2/subscriptions \
--header 'Authorization: Bearer 
After clicking the export button, your subscription data will be compiled into a CSV file. Download the file to access a complete export, including subscription details, associated customer, estimated ARR, next payment, and more.
The subscription is not charged while paused. You can reactivate it anytime (instantly
or later).
* **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.
Additionally, you can choose to archive a subscription by using the 'Delete subscription' action. The subscription will then no longer be displayed in the history list.
***
## Using the API
You can also decide to manage subscriptions using the Hyperline API. Visit our API reference documentation for more details.
* [Create subscription update endpoint](../../api-reference/endpoints/subscriptions/create-subscription-update)
* [Cancel subscription endpoint](../../api-reference/endpoints/subscriptions/cancel-subscription)
# How do subscriptions work?
Overview of the subscription concept
In Hyperline, **the subscription model is the link between products (or a plan) and a customer**.
The subscriptions can be created via the customer page on the product by an Hyperline user, or orchestrated via the technical API.
## Subscriptions lifecycle
A customer can have one or multiple subscriptions at the same time. These subscriptions can be active (running), scheduled to start in the future, or scheduled to be automatically cancelled. This makes it easy to plan any changes or bill products with a different payment schedule and renewal logic.
Hyperline provides the flexibility to specify a commitment subscription period, which may differ from the billing interval of the product it encompasses. Furthermore, the billing intervals can also vary between different products.
A subscription **will automatically be invoiced** following the schedule described below once it's active.
If you need to pause invoicing, you can pause the subscription directly in the interface using the "Pause payment collection" option.
For more details on how to manage your subscriptions please see [this page](../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 will be invoiced at the next payment date.
* `cancelled` The subscription has been canceled from an active state.
* `voided` The subscription has been voided directly from the pending state.
* `paused` The subscription's payment collection is paused.
* `errored` We attempted 4 times (3 retries) and failed to charge a subscription's invoice, see [Handling payment errors](../payments/payment-errors). Here, we consider the subscription as inactive (as the customer failed to pay you) meaning that we won't invoice the customer in the future nor collect payment. You can choose to reactivate it manually.
### When is a subscription billed?
Hyperline lets you decide when to bill each product independently, either at the start or the end of the billing period. Usage-based product will always be billed at the end of the period, depending on the consumption.
You will find several options allowing you to adjust many aspects of the subscription:
#### Update products on the subscription
You can update the products that have been added to your subscription as well as remove them and add new ones
#### Add a product to a subscription
You can add a product to a subscription at any time. The product will be added to the subscription and the customer will be charged according to the options you choose.
In this step, you can override anything on the product such as it's price or name.
* **Do not charge:** Adds the product to the subscription without charging your customer.
* **Charge pro-rata:** Charges your customer a pro-rata amount based on the remaining time in the billing period.
* **Charge full price:** Charges the full price of the product to your customer immediately.
You will see a small recap of the options you chose. on the same page.
Click on **Add product** to confirm your selection.
* **Do not refund:** Removes the product from the subscription without issuing a refund to your customer.
* **Refund pro-rata** Refunds your customer a pro-rata amount based on the remaining time in the billing period.
* **Refund full price** Refunds the full price of the product to your customer immediately.
You will see a small recap of the options you chose. on the same page.
Click on **Remove product** to confirm your selection.
#### Update product prices
You can update the price of a product on a subscription at any time.
#### Applying and removing coupons
# Connect with BigQuery
Pull data automatically from your BigQuery project
This guide is specific to setting-up a dataloader 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 setup 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 Editor**, then click "Continue" and "Done".
4. Find the newly created service account in the list, click on the service account, go to the "Keys" tab, then click "Add Key" and choose "Create new key.", choose JSON and click Create.
## Load your data
To get start, 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, choose a name and then save the connection.
When creating or updating a connection, Hyperline always performs a ping test to check the database is accessible, so if it's save, it's all good.
# Configure your first usage-based subscription
To configure a usage-based subscription, you first need to connect your data as Hyperline will need some dataset for you to configure usage-based products. If it's not done already, you can use a [CSV file](./import-events-csv), our [API](./send-your-usage-data) ou [data loaders](./usage-data-with-connectors).
When your first events have arrived, you'll be able to create a usage-based product [here](https://app.hyperline.co/app/products/create/select/).
Select the usage based product, then configure your options and your metering to attach your product to the data you want to bill. Metering can be configured in many different ways, to know more you should take a look at our [product catalog guide](../products/overview#usage).
Once the product is setup and at least one recurring price is defined, you'll be able to assign it to a subscription.
Head over to the subscription tabs and click on [new subscription](https://app.hyperline.co/app/subscriptions/create), select your customer and then click on add product.
Select your product, an interface will appear for you to configure prices, the subscription schedule and various parameters.
If you want to learn more about metering options on a subscription, read our [metering guide](../products/metering).
Click on payment settings and assign the subscription using the `Manually later` option, you'll be redirected to the customer page, the subscription should display the current usage.
If you're in [test mode](../get-started/sandbox), you'll be able to simulate new events directly from the "events" tab.
If you want to explore your consumption, you can click on the little eye icon next to the unit count, it will open the live consumption modal and will give you the detail of your consumption.
And done! Feel free to browse our documentation specific to subscriptions or to contact us on Intercom to get some help on your use case!
# Automated seat-based billing
We're improving our seat-based products by integrating metering capabilities.
## Concept
Seat-based billing is a prevalent model, typically managed manually by companies using subscription update APIs in tools like Hyperline.
Here's the typical process:
The process can become more intricate if you're seeking **automatic updates** to prevent immediate charges to users, or if your billing needs involve specific payment terms.
For instance, if you want to bill customers yearly on a pro-rated basis at each month's end based on the maximum number of users, you would need to:
1. Monitor initial and peak monthly seat counts.
2. Schedule monthly updates for yearly subscriptions.
3. Wait until the end of the month or manually calculate earnings.
4. Manually calculate pro-rated charges unless using a flexible billing tool.
Our goal is to automate these steps directly in Hyperline.
## Theoretical Differences
How do metered and seat-based items differ?
| Seat-based | Metered |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Invoiced at the end of the period based on data used | Invoiced at the start of the period, end of the period or in real-time (when an event occurs) |
| Resets every period (meaning when we restart a period we restart the count) | Can be invoiced outside of the base schedule (a yearly item can be reviewed monthly) |
| Does not consider the time for each "event" | Considers timestamps |
| No pro-rata management as we don’t track when an item is added | Pro-rata management |
| Useful for: API calls, financial flows | Useful for: users, devices, connectors… anything that’s always live |
## Practical Application
### How to create an automated seat-based product?
#### Invoicing schedule
* **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 (so if the update is realtime but invoicing is at the end of the month, we’ll update the subscription count in realtime but will then add the charge to the next invoice).
* **Custom**: Allows the user to set an invoicing period, for instance, if they have an annual subscription they want to update in realtime but want to charge the update every month.
#### Other parameters
* **Application schedule**: We'll apply the update to the subscription immediately or wait until the end of the period. It doesn't impact billing but it affects the subscription values.
* **Charging method**: If prorata is selected, we'll charge the units at the pro-rated rate given the product payment interval. Full amount means we'll charge the entire price regardless of when the change is detected.
* **Charge the highest detected value for the period**: Instructs Hyperline to use the highest value it has counted regardless of the current one. Useful to always commit the maximum number of seats.
* **Refund when a decrease in unit count is detected**: Instructs Hyperline to count negative updates as refunds if they’ve already been paid.
## 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.
More detailed information can be found in the [Explore usage consumption section](/docs/usage/explore-usage-consumption).
# Explore your data usage
Exploring your data usage to understand how your customers are consuming your products
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.
This view is global and will show all the events that are being tracked.
However, for each subscriptions and invoices, you can explore a more detailed view of the events.
## Explore usage data
You will be able to view the product's consumption along with the amount billed for each event.
In order to do so, an action **Explore consumption** is available on 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.
This can be found in the 'Subscription Details' section.
Here, you can view and analyze the usage data associated with each subscription.
## Download usage data
In order to analyze and process your usage data, you can download it in CSV format by clicking on the **Export CSV** button.
Then you'll obtain a CSV file with the following columns:
## Customise displayed event name
The event name can be customized when you create or edit the product.
It will be used to identify the event in the consumption.
In order to have a dynamic name for each event, it can depend 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.
# Import events with a CSV file
## Format your file
To write a well-formatted events CSV file, you should follow these guidelines:
* Use a comma as the delimiter to separate fields.
* Use double quotes to enclose fields that contain commas or line breaks.
* Use a header row to describe the contents of each column.
* Use a consistent date and time format, such as ISO 8601.
* Use a consistent format for nested fields, such as `record/id` and `record/amount`.
* All fields are mandatory, except for the `record` field, which can contain any number of nested fields.
Here is an example of a well-formatted CSV file that follows these guidelines:
### Example
```csv
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-"
```
Note that:
The `timestamp` field follows the ISO 8601 format.
The `record` field contains nested fields, such as `record/id`, `record/amount`, and `record/is_live`.
* The `record/id` field contains an integer value, so it does not need to be enclosed in quotes.
* The `record/type` field contains a string value, so it needs to be enclosed in quotes.
* The `record/is_live` field contains a boolean value, so it does not need to be enclosed in quotes.
## Load your file
To get start, just go to the [events explorer page](https://app.hyperline.co/app/events/explore) in Hyperline.
To upload your CSV file, click on the `Import events from CSV` button at the top right corner of the page.
This will open a modal where you can select your file.
You can also download a template file by clicking on the `Get the CSV template` download button.
This file contains the header row and an example event, which you can use as a starting point for your own events CSV file.
Once you have selected your file, click on the `Import CSV file` button to start the import process.
If there are no errors or warnings, your events will be imported into Hyperline and will be available for analysis and visualization.
# Connect with MongoDB
Pull data automatically from your MongoDB database
This guide is specific to setting-up a dataloader 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 start, 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 setup 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 dataloader directly below the new connection, you'll be asked to prompt a JSON query.
Your query needs to include a `collection` attribute pointing to your base collection, because opposed to tranditional 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, with everything outside of "collection" being valid MongoDB query fields (you can use aggregate, lookups, filters...).
Hyperline will parse the JSON from your input and transform 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.
# Send your usage data
Sending usage data is the first thing to do to unlock Hyperline's potential when you have a usage based model, but there are a few tips to make the most out of our system.
First, **we're not an analytics API**, sending us 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 anyways. If you need a great product analytics solution, we recommend you check out our friends at [June.so](https://june.so/) or at [Mixpanel](https://mixpanel.com/).
This being said, you shouldn't restrain from sending data that you're not using yet. Hyperline is designed for you to iterate on your pricing & packaging and will allow you to run experiments and simulations from the data we have ingested.
The best way to think about events to send us is to ask yourself if you'll use the data either
* To price your product (ex: price per user or per API call)
* Limit usage (ex: free up to 5GB of storage)
* Orchestrate pricing-related workflows (ex: when a customer reaches X, show a paywall).
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
Events payloads always follow the same (minimalist) structure and can be sent to the [POST `/events` endpoint](../../api-reference/endpoints/billable-events/create-billable-event). The `record` object can contain any additional properties of type `string`, `number`, `boolean`, and array of these types but arrays of objects will be rejected.
Events are processed instantly, you can go to your [events page](https://app.hyperline.co/app/events/explore) and refresh it to see it.
You can send as many as 50 events per second before being rate-limited. We'll increase these limits as our infrastructure grows, please contact us if you need a custom limit.
Here's an example payload
```json Event
{
"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 we're making some basic security check, we can't filter every personal or confidential data off our systems automatically.
Most of the time you don't need personal information in Hyperline so we recommend you 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's identity or localization
In our systems, we're responsible for keeping your data safe, but you're in charge of the content itself, so be careful, your customer's safety is an important matter.
## Events or entities?
Hyperline is designed to rely fully on events for data ingestion. We 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 our database, independently of its timestamp.
For instance, let's say you want your customer to pay 5€ per user, you'll send us the following *event* when a new user is registered.
```json Event
{
"customer_id": "
We offer you a preview of the evolution of this pricing to make it more visible regarding how it evolves with the increase of items.
## Update and delete events
Now you may be thinking, what happens if I send an event that shouldn't be billed? Or if need to make a change to an entity?
Hyperline's API is an append-only system, meaning that except through our interface, we don't allow update or delete operations. But don't worry, we got you covered.
### 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 will consider that this new event overrides the previous one and therefore will replace it in the database.
In other words, updating an event is just like creating one, just send the same payload with the updated field and it will be updated.
To find out which event is the latest, we're using the `timestamp` value.
Using our users again, here's an example where we add a "status" property
```json
{
"customer_id": "
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.
## 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
# Connect with Snowflake
Pull data automatically from your Snowflake warehouse
This guide is specific to setting-up a dataloader 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 start, 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, Hyperline will only need a read access to the tables you need to synchronise.
## Load your data
Snowlake is a standard SQL loaders and you just to write a Snowflake compatible SQL query. Hyperline will run it as the role/user that was used to connect to the database.
As always, make sure to include an `id`, `customerId` and `timestamp` fields with the correct casing.
# Pull usage data with connectors
No-code usage based with Hyperline connectors and automatic data pulling
If you don't fancy integrating our API, we have released a connector system allowing you to import data directly from your own database.
## Prerequisites
* You need a Postgres database that can receive incoming trafic 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`)
The best practice here is to use a read replica and create a limited user specifically for us that will only be able to access the needed subset in the database.
## Load your data
To get start, just go to the [data loaders page](https://app.hyperline.co/app/events/loaders) in Hyperline. You should see an empty state.
Let's add your first connection by clicking on "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 on submit, we do a quick check to make sure your database is accessible by running a blank query. You should now see your connection live.
Time to create pour first loader by clicking on "New data loader" on the right side of the screen. This opens up a slightly longer modal but don't worry, it's really easy.
* Select the connection you just created
* Set an Event type for this query, it's the identifier we'll use later in the product to refer to the data from this query. It could be `api_calls` or `active_users` for instance
* Select the refresh rate depending on your use case, to get started every hour is largely sufficient
## Getting the SQL right
Now it's time to start typing your query. Hyperline will need a few things from you and expect a specific format as the query output.
We'll need 3 fields to validate the query:
* `timestamp` will represent the date we use to calculate if a record should be included in an invoice. For instance, if you bill on monthly API calls, we'll bill all events with a timestamp within the last 30 days. It's less important if you don't have periodic metering
* `customerId` is the customer unique identifier **ON YOUR SIDE**. We'll use it to associate a record with a subscription.
* `id` is the identifier of the record **ON YOUR SIDE**. We'll use it to de-duplicate and update records later, so make sure it really represents the record uniquely.
When importing records, Hyperline will try to match an existing customer or create a new one with a status `automatically_created` that won't be displayed by default in your customers list to avoid spam (but you can access them using the `pending customers` table).
Optionally, you can also return a `customerName` property so we had a name to the customer when creating it, which will make it easier for you to find them later.
To to summarise, the minimum acceptable request looks like this
```sql
-- 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
-- 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
```
That's the minimum for a query to be accepted and loaded into Hyperline. You can then add any other fields to your query, but please make sure you only include what's necessary to keep data sharing to the bare minimum.
Then click on preview query, we'll validate the presence of the required fields and display a preview of 5 records so you can make sure everything is in order.
Save the data loader and go to your events page, after a few seconds, you should see a table with your newly ingested events. We're limiting exploration capabilities for now but will add more features later. See it as a debugger.
### Updating records
Hyperline automatically updates existing records, we're using a combination of the supplied `id` and `customerId` and always keep the latest version. We don't update customer names in Hyperline even if the name has changed, you'll need to change in the interface.
### Deleting records
Hyperline doesn't delete records automatically to avoid any issue, we recommend that you add a `deletedAt` fields in the query that you set to something when the record is deleted. You'll then be able to filter these records out in our pricing engine.
### Loading big tables
Hyperline processes query in batches, so you should be covered as long as your query is reasonable (we can process up to 120k rows per minute). If your table is bigger that this, consider importing only records that have been updated after the last refresh, or importing them less often. It's actually quite easy.
```sql
-- Adapt this to your refresh time
SELECT xxx FROM table WHERE (updated_at + interval '60 minutes') > NOW()
```
# Overview
Overview of the wallet concept
## Use cases for wallets
Wallets allows you and your customers to pre-pay funds to be automatically used by Hyperline's system when paying invoices. This feature is particularly useful when you want to set up upfront payments in pay-as-you-go flows, or offer free funds to your customers.
There are 2 main concepts when starting with wallets in Hyperline:
* **Wallet settings**: configured at your account level and shared for all your customers
* **Wallet**: configured at your customer level and unique to the customer
In Hyperline, a wallet contains money in the currency of your customer.
### Allow users to buy top-up from the portal
You can choose to enable this option in the wallet settings.
Then, users will be able to add funds with their current payment method directly in their portal.
## Create a wallet for a customer
Now that you have enabled wallets in the settings page, you will be able to create wallets for your customers from Hyperline.
To do so, go to Hyperline main menu, in the **Customers** section.
Navigate to the **Wallet** tab, and click on **Create wallet.**
## Manage wallets
Once you have created a wallet, you can come back to it anytime to **Top-up** or **Pause the wallet payment** if you need to. Those are done through the wallet **Action** menu.
***
# Using the API
You can also decide to manage wallets using the Hyperline API. Visit our API reference documentation for more details.
* [Get wallet settings endpoint](../../api-reference/endpoints/wallets/get-wallet-settings)
* [Update wallet settings endpoint](../../api-reference/endpoints/wallets/update-wallet-settings)
* [Get wallet endpoint](../../api-reference/endpoints/wallets/get-wallet)
* [Create wallet endpoint](../../api-reference/endpoints/wallets/create-wallet)
* [Get wallet transactions endpoint](../../api-reference/endpoints/wallets/get-wallet-transactions)
# Manage wallet balances
Learn about top up, debit and balances
**Paid top-up** are funds your customer paid (or will pay) for. **Free top-up**
are an offer you are making to the customer (the funds will be added for free).
### Top-up from the customer portal
You can make your customers autonomous by offering them to top-up through their portal.
Once the process is complete, you will notice the GoCardless status change to 'Active' in the Payment tab.
## Payment methods
Now that you have successfully activated your account, it will be automatically designated as the primary payment gateway for the following transaction types:
* **SEPA Direct Debit**: GoCardless accepts payments in Europe and in UK.
## Customer information
Each time you've successfully created and billed a customer in Hyperline, the corresponding customer profile and payment details are automatically generated in your GoCardless account.
If you want to double check you just have to on the Payments and Customers tabs on your Gocardless dashboard.
After finishing the model, you can also configure more settings on it like columns types, descriptions, etc.
## Installation
Before installing the component, ensure that you have a HubSpot account connected to Hyperline. If not, please refer to the [setup guide](./overview#setup) for instructions.
This component is **automatically installed when you connect your account**, requiring no manual action from you. It will appear directly on your company views once the setup is completed.
## Behavior
Once installed, this component can be found on both `company` or `deal` views, on the right side panel.
From it, you can directly manage your Hyperline customer, create new quotes, assign subscriptions, and manage existing subscriptions for your HubSpot company.
When loaded on the CRM side, the component will **automatically create the first time (and if it doesn't exist yet) a corresponding user on Hyperline** using the user email address from the CRM and the ['Account manager' role](../../docs/get-started/configure-account#account-manager-role).
### Root object
You can control the component's behavior and determine whether the root object displaying the billing details for the customer is Company or Deal.
# HubSpot
Learn how to connect HubSpot with Hyperline
The Hyperline HubSpot integration offers seamless synchronization of your HubSpot companies, quotes, subscriptions and invoices enabling effortless data transfer between Hyperline and your HubSpot instance without any manual effort or technical configuration.
Additionally, Hyperline provides you with a dedicated component that can be inserted into your HubSpot Company page, allowing you to assign and manage your subscriptions using the full-powered Hyperline UI directly within your CRM. [See more details](./component).
By doing so, the Hyperline integration empowers your business teams to **maintain Salesforce as their primary tool while capitalizing on the capabilities offered by Hyperline**.
## Prerequisites
You need to have a valid [HubSpot account](https://hubspot.com/) and admin rights on Hyperline.
We recommend you to **experiment with a test account** before going live. For this you can create a dedicated free [HubSpot account](https://app.hubspot.com/signup-hubspot/crm) for your testing, and use the [test mode](../../docs/get-started/sandbox) of your Hyperline account.
### Custom objects
In order to synchronize data, Hyperline needs specific custom objects on your HubSpot account. If the custom object doesn't exist, you won't be able to activate the synchronization for this entity and no data will be pushed to HubSpot.
| Entity | HubSpot Object Name |
| -------------------- | --------------------------------- |
| Quote | `hyperline_quotes` |
| Quote line item | `hyperline_quote_line_items` |
| Quote coupon | `hyperline_quote_coupons` |
| Subscription | `hyperline_subscriptions` |
| Subscription product | `hyperline_subscription_products` |
| Subscription coupon | `hyperline_subscription_coupons` |
| Invoice | `hyperline_invoices` |
| Invoice line item | `hyperline_invoice_line_items` |
More details about the fields meaning can be found in the API reference for [quote](../../api-reference/endpoints/quotes/get-quote), [subscription](../../api-reference/endpoints/subscriptions/get-subscription) and [invoice](../../api-reference/endpoints/invoices/get-invoice).
## Setup
For customers you can decide to select the **synchronization direction** (one-way or bidirectional) and determine **which HubSpot companies to import** into Hyperline (all accounts or specific/flagged ones).
### Flagged companies
During integration setup, Hyperline will create a **Sync to Hyperline** checkbox field on the HubSpot Company object (`hyperline_sync` field).
When choosing the 'Only specific companies' option, the integration will import and synchronize companies where the **Sync to Hyperline** checkbox is selected, disregarding other companies.
This option will sync the customer details, and push its subscriptions and invoices.
Additionally, you can use the "Re-synchronize" button anytime for a customer already sent to HubSpot. This actions retriggers the synchronisation.
## Reconcile Hyperline Customer and HubSpot Company
When a Hyperline Customer is created, a corresponding Company is created in HubSpot. Similarly, when a HubSpot Company is created or updated with the 'Sync in Hyperline' field enabled, a corresponding Customer is created in Hyperline. Both Customer and Company entities are then linked.
To associate an existing Customer (created before connecting your HubSpot account) with an existing Company, you can fill the "Hyperline ID" (`hyperline_id`) field in your Company object. This action ensures synchronization between both entities. We recommend to perform this operation prior to enabling the 'Sync in Hyperline' field. Failing to do so might result in duplicates, where an Company could sync to Hyperline without the `hyperline_id` value in the meantime.
## Disconnect
At any time, you can disconnect the integration by clicking on the **Disconnect** button located in the top-right corner of the HubSpot integration settings page.
Disconnecting will halt synchronization, but the custom fields and previously pushed data in HubSpot will remain intact; they won't be erased.
# Mollie
Learn how to collect payments through Mollie on Hyperline
## Prerequisites
You need to have a [Mollie account](https://my.mollie.com/dashboard), a [profile](https://my.mollie.com/dashboard/settings/profiles) with payment methods (Cards and/or SEPA Direct Debit) activated, and admin rights on Hyperline.
## Set-up
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 on **Connect** for Mollie
This will redirect you to the Mollie login page where you will have to enter your account credentials and click on **Continue**.
Once the process is completed, you will see the Mollie status change to `Active` in the Payment tab.
## Payment methods
Now that you have successfully activated your Mollie account, it will be automatically designated as the primary payment gateway for the following transaction types:
* **Card transactions**: Whenever your customers make payments using credit or direct debit cards.
* **SEPA Direct Debit**: Mollie accepts payments in Europe and in UK.
## Customer information
Each time you've successfully created and billed a customer in Hyperline, the corresponding customer profile and payment details are automatically generated in your Mollie account.
This seamless integration ensures that your customer data and payments are synchronized between Hyperline and Mollie, streamlining your management of transactions and customer information.
## Installation
Before installing the component, ensure that you have a Salesforce account connected to Hyperline. If not, please refer to the [setup guide](./overview#setup) for instructions.
This component is **automatically installed when you connect your account**.
To add it on your account's or opportunity's page:
1. Navigate to any account's or opportunity's page
2. Click on the top right menu and select 'Edit Page'
3. Search for the 'Morph...' component and drag-and-drop it to your page editor
4. Save (if it's your first time editing the page layout, you'll be prompted to Activate the view)
## Behavior
Once installed, this component can be used on both `Account` or `Opportunity` views.
From it, you can directly manage your Hyperline customer, create new quotes, assign subscriptions, and manage existing subscriptions for your Salesforce account.
When loaded on the CRM side, the component will **automatically create the first time (and if it doesn't exist yet) a corresponding user on Hyperline** using the user email address from the CRM and the ['Account manager' role](../../docs/get-started/configure-account#account-manager-role).
### Root object
You can control the component's behavior and determine whether the root object displaying the billing details for the customer is Account or Opportunity.
# Salesforce
Learn how to connect Salesforce with Hyperline
The Hyperline Salesforce integration offers seamless synchronization of your Salesforce accounts, quotes, subscriptions and invoices enabling effortless data transfer between Hyperline and your Salesforce instance without any manual effort or technical configuration.
Additionally, Hyperline provides you with a dedicated component that can be inserted into your Salesforce Account page, allowing you to assign and manage your subscriptions using the full-powered Hyperline UI directly within your CRM. [See more details](./component).
By doing so, the Hyperline integration empowers your business teams to **maintain Salesforce as their primary tool while capitalizing on the capabilities offered by Hyperline**.
## Prerequisites
You need to have a valid [Salesforce account](https://salesforce.com) and admin rights on Hyperline.
We recommend you to **experiment with a Developer Account** before going live. For this you can create a free [Salesforce Developer instance](https://developer.salesforce.com/signup), and use the [test mode](../../docs/get-started/sandbox) of your Hyperline account.
### 1. Permissions
Hyperline automatically sets up technical mechanisms in your Salesforce instance upon connection to enable notifications and benefit from real-time synchronization.
For this, we recommend using a user with the **System Administrator** profile when connecting your Salesforce instance. Otherwise, the user account used needs to have specific permissions.
5. Proceed the same way for all the objects you want to synchronize
More details about the fields meaning can be found in the API reference for [quote](../../api-reference/endpoints/quotes/get-quote), [subscription](../../api-reference/endpoints/subscriptions/get-subscription) and [invoice](../../api-reference/endpoints/invoices/get-invoice).
## Setup
You have the option to select which data and entities (customers, invoices, subscriptions) you want to synchronize.
Additionally, for customers you can decide to select the **synchronization direction** (one-way or bidirectional) and determine **which Salesforce accounts to import** into Hyperline (all accounts or specific/flagged ones).
### Flagged accounts
During integration setup, Hyperline will create a **Sync to Hyperline** checkbox field on the Salesforce Account object (`HyperlineSync__c` field).
When choosing the 'Only specific accounts' option, the integration will import and synchronize accounts where the **Sync to Hyperline** checkbox is selected, disregarding other accounts.
This option will sync the customer details, and push its subscriptions and invoices.
Additionally, you can use the "Re-synchronize" button anytime for a customer already sent to Salesforce. This actions retriggers the synchronisation, pushing all associated details such as subscriptions and invoices.
## Reconcile Hyperline Customer and Salesforce Account
When a Hyperline Customer is created, a corresponding Account is created in Salesforce. Similarly, when a Salesforce Account is created or updated with the 'Sync in Hyperline' field enabled, a corresponding Customer is created in Hyperline. Both Customer and Account entities are then linked.
To associate an existing Customer (created before connecting your Salesforce instance) with an existing Account, you can fill the "Hyperline ID" (`HyperlineId__c`) field in your Account object. This action ensures synchronization between both entities. We recommend to perform this operation prior to enabling the 'Sync in Hyperline' field. Failing to do so might result in duplicates, where an Account could sync to Hyperline without the `HyperlineId__c` value in the meantime.
## Disconnect
At any time, you can disconnect the integration by clicking on the **Disconnect** button located in the top-right corner of the Salesforce integration settings page.
Disconnecting will halt synchronization, but the custom fields and previously pushed data in Salesforce will remain intact; they won't be erased.
# Segment
Learn how to ingest events from Segment
## 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, and then aggregate it to monitor performance, inform decision-making processes, and create uniquely customized user experiences.
All this data can be easily sent 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.
# Slack
Learn how to send automated messages to Slack
## 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.
## Send messages from Hyperline to Slack
As an example, this guide sets up a workflow to send your current Annual Recurring Revenue (ARR) to a dedicated Slack channel every day.
For this, we'll create and use a [Zapier zap](./zapier) using the Hyperline app.
Once the process is completed, you will see the Stripe status change to `Active` in the Payment tab.
## Payment methods
Now that you have successfully activated your Stripe account, it will be automatically designated as the primary payment gateway for the following transaction types:
* **Card transactions**: Whenever your customers make payments using credit or direct debit cards.
* **Direct Debit**: In cases where your customers use SEPA (Europe), ACH (US), or Bacs (UK) direct debit for payments.
## Customer information
Each time you've successfully created and billed a customer in Hyperline, the corresponding customer profile and payment details are automatically generated in your Stripe account.
This seamless integration ensures that your customer data and payments are synchronized between Hyperline and Stripe, streamlining your management of transactions and customer information.