Skip to main content

​
Prerequisites

You need to have a Sphere account.
Hyperline uses one tax engine at a time per invoicing entity. If you use Sphere for an invoicing entity, Sphere calculates the tax of all its invoices, so configure your products and tax registrations in Sphere first.

​
Setup

Hyperline activates the Sphere integration on request. Contact us to enable it on your account, then follow the steps below.

​
Get your Sphere API key

  1. In your Sphere dashboard, open the API keys settings.
  2. Create an API key for Hyperline and copy it.

​
Connect Sphere

  1. In Hyperline, go to Settings > Integrations and click Connect on the Sphere card.
  2. Paste your API key and confirm. Hyperline checks the key with Sphere before saving the connection.
The connection appears as API key ending in followed by the last characters of your key, so you can tell several connections apart.

​
Assign invoicing entities

A Sphere API key belongs to a single Sphere account. If your invoicing entities are registered in different Sphere accounts, connect one API key per account and assign each connection to its invoicing entities.
  1. On the Sphere card, open the connection settings.
  2. In Invoicing entities, select the entities whose tax this connection calculates, then save.
To add another Sphere account, use Connect another account from the Sphere card menu.
A connection with no invoicing entity assigned calculates tax for every entity that no other connection covers. An invoicing entity can only be assigned to one Sphere connection.

​
Select Sphere as tax engine

In the settings of your invoicing entity, click Taxes and select Sphere as tax engine. Sphere is selectable once a connection is verified.

​
Configure products

Sphere reads the tax code of each invoice line from its Sphere product. Hyperline sends each line to Sphere under the ID of its Hyperline product. The first time Sphere sees a product, it creates it in your account with your account’s default tax code. In your Sphere dashboard, open each product created by Hyperline and give it the tax code you want to apply.
Until you set its tax code in Sphere, a product is taxed with your account’s default tax code. Invoice lines without a Hyperline product are taxed against the Sphere product default_hyperline_product_sphere.

​
How taxes are calculated

For each invoice, Hyperline sends Sphere the customer’s address, tax ID, and invoice lines, and stores the tax Sphere returns on each line.
  • Address: Sphere uses the invoice’s shipping address when there is one, otherwise the billing address. See shipping address for how a subscription’s shipping address is selected.
  • Tax ID: when the customer has a tax ID, Sphere applies the reverse charge where it is due, and the invoice shows the reverse-charge statement.
  • Exemptions: when Sphere reports a product as exempt in the customer’s jurisdiction, Hyperline marks the line as exempt.
  • Tax-exempt customers: Hyperline doesn’t send customers marked as tax-exempt to Sphere and invoices them without tax.
The tax rate shown on an invoice is the tax amount divided by the amount excluding tax. In the US, it can differ from the jurisdiction’s headline rate. For example, a state may tax only part of the price of a product, or state, county, and city taxes may add up.

Example 💡

In Texas, SaaS is taxed on 80% of its price. For an invoice of $100 shipped to Austin, where the combined rate is 8.25%, Sphere calculates $6.60 of tax and the invoice shows a 6.6% tax rate.
If Sphere cannot locate the customer’s address, Hyperline creates the invoice without tax. Complete the customer’s address, then edit the draft invoice and choose to update the customer details to recalculate its tax.

​
Limitations

  • Hyperline uses Sphere to calculate tax only. Hyperline doesn’t record invoices and credit notes as transactions in Sphere.
  • To disconnect a Sphere connection, contact us.