Skip to main content
Sphere is a tax compliance platform. It calculates sales tax, VAT, and GST in real time and records your transactions so they can be filed in each jurisdiction where you’re registered. You can use Sphere with Primer Checkout today. You call Sphere from your server and pass the result to Primer through the client session. Primer doesn’t call Sphere for you, so this guide shows where each call fits.
You build this integration yourself. There’s no Sphere connection to set up in the Primer Dashboard.
This guide covers how Sphere fits into a Primer integration. For the full list of fields, error codes, and rate limits, see Sphere’s documentation:

How it works

Tax depends on the customer’s address, so where the tax calculation fits depends on when you create the client session: Either way, Primer Checkout shows the total including tax on the pay button. The rest of the flow is the same:
  1. After the payment is captured, your server records the sale in Sphere with the same tax calculation, so the tax you file matches the tax you charged.
  2. Refunds are recorded in Sphere as credit notes, and chargebacks as cancellations.

Before you begin

  • A Sphere account, with an API key that can call both calculate_tax and the Transaction API.
  • A Sphere product tax code for each product you sell. Ask Sphere which codes apply to you.
  • A Primer account with a workflow that processes payments for your checkout.
  • A Primer server-side integration that creates client sessions.

Integration steps

The examples below use an order with two lines, for a customer in New York: a Pro plan at $1,200.00 and two extra seats at $150.00 each.
A runnable sandbox example of this integration, using the same order, is on GitHub: Sphere tax with Primer Checkout. It covers both ways of adding tax to the client session, the payment guard, failing open when Sphere is unavailable, and recording sales, credit notes and cancellations in Sphere. The folder includes an AGENTS.md file, so you can point a coding agent at it.
1

Create your products in Sphere

Sphere needs to know each product and its tax code before it can calculate tax on it. Create or update each product once, and again whenever your catalog changes:
Use the same product ID in Sphere as the itemId you use in Primer, so each line maps across directly.
2

Calculate tax with Sphere

Once you have the customer’s address, call Sphere’s calculate_tax from your server. Send one line per order line. Each line’s amount is the line total after discounts, in the currency’s smallest unit (for example, cents). So $1,200.00 is sent as 120000.
For a business customer, also pass their VAT or tax ID as tax_id.The response has a sphere_tax_calculation_id and the tax for each line (shortened here):
CALCULATION_ID stands for the sphere_tax_calculation_id value, a UUID. A line can have more than one entry in tax_amounts, one per tax that applies. The line’s tax is their sum: $106.50 for the Pro plan, and $26.62 for the extra seats. Store the sphere_tax_calculation_id with your order. You’ll need it in step 5.When no tax is due, for example where you aren’t registered, the response has empty or zero tax_amounts. It may or may not include a sphere_tax_calculation_id. If it does, pass it when you record the sale. If it doesn’t, record the sale without one.
3

Add the tax to the client session

Set each line item’s taxAmount to the tax Sphere returned for that line. taxAmount is the tax for the whole line, not per unit. Primer calculates the payment amount for each line as amount × quantity − discountAmount + taxAmount, so you never set the total yourself.How you do this depends on when you create the client session.
Calculate tax first (step 2), then create the client session with the tax and the customer’s address already in it:
Primer Checkout shows the total including tax ($1,633.12) as soon as it loads. You don’t need to update the session or refresh Primer Checkout.If the customer can still change their address or order on the checkout page, calculate tax again and update the session, as shown in the other tab.
4

Don't let a payment start with out-of-date tax

This step matters most when the address is collected in checkout, or when the customer can change it there. refreshSession() has no effect once a payment has started, so tax must be final before the customer pays. Use primer:payment-start as a guard: if tax wasn’t calculated for the address currently on screen, abort the payment.If you fail open when Sphere is unavailable, let the payment continue in that case too. Otherwise the guard blocks every payment during an outage.
Use a new idempotency key for each payment attempt. If you reuse the key after a declined payment, the customer’s retry fails.
5

Record the sale in Sphere

Once the payment is captured, record the sale in Sphere with POST /v1/transactions.Confirm the payment on your server first, rather than relying on the browser. Either listen for the payment status webhook, or fetch the payment with GET /payments/{id}. Check that its status is SETTLED or PARTIALLY_SETTLED, and that its orderId and amount match your order. Don’t record the sale while the payment is SETTLING: some processors capture asynchronously, and a SETTLING payment can still be cancelled. Wait for the payment status webhook to report SETTLED.
Sphere records a total of $1,633.12, including $133.12 tax, matching what the customer paid. A few details matter here:
  • Pass sphere_tax_calculation_id. Sphere then records the exact tax the customer saw, instead of recalculating it. Line external_id values and amounts must match the lines you sent to calculate_tax, or Sphere rejects the calculation ID.
  • Send the customer’s tax ID. For a business customer, add customer_tax_ids, for example [{ "tax_id": "DE123456789", "country": "DE" }]. Otherwise the sale is recorded without it, which matters most when there’s no calculation ID, such as a fail-open sale.
  • Use the order ID as external_id. Sphere treats repeated requests with the same external_id as the same transaction, so retries don’t create duplicates.
  • Set finalized_on to when the payment was captured. Otherwise Sphere uses the time of the request, and a late retry could move the sale into a different tax period.
  • Convert amounts. Primer and calculate_tax take amounts in the currency’s smallest unit, as whole numbers (120000 for $1,200.00). The Transaction API takes amounts in the main currency unit, as text ("1200.00").
Decide when to record the sale: at capture or at authorization.Sphere recommends recording the sale at capture, provided capture is attempted immediately when the customer completes checkout. The tax is due once the customer has agreed to pay and is charged. If an immediate capture fails, you don’t record anything.If you authorize first and capture later, for example when you capture on shipment, this is your decision:
  • Record at capture. Record the sale when the payment reaches SETTLED or PARTIALLY_SETTLED. Authorizations that are voided are never recorded.
  • Record at authorization. Record the sale when the payment reaches AUTHORIZED. If you later cancel the authorization instead of capturing it, cancel the Sphere transaction with POST /v1/transactions/{external_id}/cancel, using the external_id you gave the sale (order-123 here).
Which one is right depends on how and when you invoice your customers. Check with your tax adviser or Sphere.
In the example: confirmPayment in server/orders.js checks the payment with GET /payments/{id} and queues the sale, which server/outbox.js sends to Sphere.
6

Record refunds as credit notes

For each refund, record a credit note in Sphere that’s linked to the original sale. A credit note reduces the amount, and the tax, of the original sale. Record one credit note per refund.For example, a $500.00 refund on the order above is split across its lines in proportion to their totals including tax: $400.00 from the Pro plan and $100.00 from the extra seats. Send the part of each that excludes tax:
Because the credit note is linked to the original sale, Sphere calculates its tax in proportion to the original sale: $40.76 here, so the credit note totals $500.00. For later partial refunds, base the split on the amount not yet refunded on each line, so the amounts excluding tax clear every line exactly.Sphere rounds the tax on each credit note separately. After several partial refunds, the total tax credited can differ from the tax on the original sale by a cent.Primer refunds can be asynchronous. Record the credit note when the refund webhook confirms the refund, rather than when the refund request returns.In the example: allocateRefund in server/refunds.js splits the refund across the lines, and confirmRefund records the credit note once Primer reports the refund settled.
7

Cancel the sale on a chargeback

For a dispute that results in a chargeback, Sphere expects the original transaction to be cancelled.

Handle Sphere being unavailable

calculate_tax runs while the customer waits at checkout. Set a short timeout, such as 2 seconds, so a slow response can’t stall your checkout. If Sphere doesn’t respond in time, or returns an error because it’s unavailable, you need to decide what happens to the customer’s payment. This is your decision.
  • Fail open (Sphere’s recommendation): let the customer pay without tax. Primer Checkout shows the total without tax, and the payment goes ahead. Make sure the payment guard in step 4 allows this.
  • Fail closed: block the payment until Sphere responds and tax is calculated.
If you fail open, still record the sale in Sphere, without a calculation ID. Sphere calculates the tax that was due on the sale and records it as owed. Mark these sales in metadata so you can find them later. Only fail open when Sphere is unavailable: timeouts, 429, and 5xx responses. Other 4xx responses mean Sphere couldn’t calculate tax for this request, and depend on the error:
  • customer_tax_location_invalid: Sphere couldn’t locate the address. Ask the customer to correct it.
  • Other errors, such as invalid_product_tax_code, are problems in your setup that the customer can’t fix. Block the payment and fix the setup.
Recording the sale with the Transaction API happens after checkout, so it can use a longer timeout. A timeout doesn’t mean the request failed: Sphere may already have recorded the sale. Retry with the same external_id until you get a response. Save each sale you need to record on your server, and keep retrying until Sphere confirms it, so no sale is lost if Sphere or your server is down. In the example: failsOpen in server/sphere.js decides when to fail open, and server/worker.js retries queued Sphere writes until Sphere confirms them.

Other things to know

  • Every sale. Calculate tax and record every sale, including sales in places where you aren’t registered. Sphere only returns tax where you’re registered.
  • One tax calculation per order. Sphere’s API doesn’t stop you from using the same calculation ID on more than one transaction, but that isn’t intended. Make sure your server only uses a calculation ID for the order it was calculated for.
  • Partial capture. Tax is due on the full order total once the order is issued to the customer, even if you capture less than you authorized. Record the full sale with its calculation ID. If the rest is never collected, record a credit note for the uncollected amount, split across lines as in step 6. For example, if you capture $1,000.00 of the $1,633.12 order and never collect the remaining $633.12, record a credit note for $633.12.
  • Address validation. Sphere uses a third-party mapping service to resolve addresses, so it may place an incomplete or invalid address (for example, a US ZIP code that doesn’t exist, with no state) in a jurisdiction rather than return an error. Validate addresses before you calculate tax.
  • Business customers and reverse charge. Pass the customer’s tax ID as tax_id. In some countries, a business customer accounts for the tax themselves instead of paying it to you. This is called reverse charge. When it applies, Sphere returns taxability_reason: reverse_charge with zero tax. Sphere checks tax IDs with the tax authority where it can. The first time it sees a tax ID, that check happens in the background, so during checkout Sphere can only check the ID’s format.
  • Recurring and merchant-initiated payments. Each charge is a separate sale. Calculate tax for each charge, set taxAmount on the line items of the payment request, and record the sale in Sphere with its own external_id and calculation ID. Don’t reuse the calculation ID from an earlier charge.
  • Up-to-date rates. A calculation ID doesn’t expire, but rates change. Calculate tax as close to payment as you can, and again whenever the address or order changes.
  • Currencies. Sphere accepts any ISO 4217 currency. The Transaction API currently stores two decimal places for every currency, so amounts in three-decimal currencies, such as KWD, are rounded.

Test your integration

  1. In your Primer sandbox, use a test card to create a successful payment.
  2. Calculate tax for addresses in places where you’re registered and where you’re not, and with and without a business tax ID. Check the tax per line, the reason for any zero-tax lines, and the total shown on the pay button.
  3. Change the address after tax is calculated, then try to pay. The guard in step 4 should block the payment.
  4. Decline a payment, then retry. The retry should succeed, because it uses a new idempotency key.
  5. Complete a payment, then check the transaction in Sphere. Its tax should match the tax calculation exactly.
  6. Make one or more partial refunds that add up to the full amount. The credit notes in Sphere should add up to the original sale, both net and tax.
If you test against the Sphere account you file from, cancel your test transactions with POST /v1/transactions/{external_id}/cancel when you’re done, so they aren’t included in your filings.

Troubleshooting

Limitations

  • Address from the payment form or a wallet. This integration assumes you have the address before payment, either from earlier in your flow or from your own form on the checkout page. If the address comes from the card form’s billing address fields, or from the Apple Pay or Google Pay sheet, you can’t recalculate tax before the payment starts. For wallets, the Express Checkout shipping address events can provide an address to calculate tax from.
  • Tax-inclusive pricing. With inclusive pricing, Sphere returns the tax contained in the price (for example, $9.09 on $100 at 10%). Primer adds taxAmount on top of amount, so you’d need to set amount to the price minus the tax. This guide covers tax-exclusive pricing only.