> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sphere

> Calculate sales tax, VAT, and GST with Sphere in Primer Checkout, and record each sale, refund, and chargeback in Sphere for filing.

[Sphere](https://getsphere.com) 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](https://primer.io/docs/checkout/primer-checkout/product-overview.md) 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.

> [!NOTE]
>
> You build this integration yourself. There's no Sphere connection to set up in the Primer Dashboard.

> [!TIP]
>
> 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:
>
> * [Tax Calculation API](https://docs.getsphere.com/features/integrations/api/tax-calculation): `calculate_tax`
> * [Transaction API](https://docs.getsphere.com/features/integrations/api/transaction-api): authentication, conventions, and errors
> * [Products](https://docs.getsphere.com/features/integrations/api/transaction-api/products): products and product tax codes
> * [Transactions](https://docs.getsphere.com/features/integrations/api/transaction-api/transactions): invoices, credit notes, and cancellations

## How it works

Tax depends on the customer's address, so where the tax calculation fits depends on when you create the [client session](https://primer.io/docs/api-reference/v2.4/api-reference/client-session-api/create-a-client-session.md):

| When you create the client session | What you do |
| - | - |
| **After you have the address.** For example, the customer entered it earlier in your flow, or it's saved on their account. | Calculate tax with Sphere, then create the client session with the tax already on each line item. |
| **Before you have the address.** The customer enters it on the checkout page. | Create the client session without tax. When the customer enters their address, calculate tax with Sphere, [update the client session](https://primer.io/docs/api-reference/v2.4/api-reference/client-session-api/update-client-session.md), and refresh Primer Checkout. |

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.

```mermaid theme={"dark"}
sequenceDiagram
    participant B as Browser (Primer Checkout)
    participant S as Your server
    participant X as Sphere
    participant P as Primer
    alt Address known before checkout
        S->>X: POST calculate_tax
        X-->>S: Tax per line + sphere_tax_calculation_id
        S->>P: POST /client-session (lineItems[].taxAmount)
        S-->>B: clientToken
        B->>B: Load checkout
    else Address collected in checkout
        S->>P: POST /client-session (no tax)
        S-->>B: clientToken
        B->>B: Load checkout
        B->>S: Customer submits address
        S->>X: POST calculate_tax
        X-->>S: Tax per line + sphere_tax_calculation_id
        S->>P: PATCH /client-session (lineItems[].taxAmount)
        B->>B: primer.refreshSession()
    end
    B->>P: Customer pays
    P-->>S: PAYMENT.STATUS webhook (or GET /payments/{id})
    S->>X: POST /v1/transactions (finalized, with calculation ID)
```

## 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](https://primer.io/docs/get-started/create-workflow.md) that processes payments for your checkout.
* A Primer server-side integration that [creates client sessions](https://primer.io/docs/get-started/set-up-a-checkout.md).

## 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.

> [!TIP]
>
> A runnable sandbox example of this integration, using the same order, is on GitHub: [Sphere tax with Primer Checkout](https://github.com/primer-io/examples/tree/main/examples/sphere-tax). 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](https://docs.getsphere.com/features/integrations/api/transaction-api/products) and its tax code before it can calculate tax on it. Create or update each product once, and again whenever your catalog changes:

```bash theme={"dark"}
curl -X POST https://api.getsphere.com/v1/products \
  -H "X-API-KEY: YOUR_SPHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "pro-plan-annual",
    "name": "Pro plan (annual)",
    "tax_code": "YOUR_SPHERE_TAX_CODE"
  }'
```

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`](https://docs.getsphere.com/features/integrations/api/tax-calculation) 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`.

```bash theme={"dark"}
curl -X POST \
  https://server.getsphere.com/tax_api/calculate_tax \
  -H "X-API-KEY: YOUR_SPHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "usd",
    "customer_id": "customer-123",
    "customer_address": {
      "address1": "350 5th Ave",
      "city": "New York",
      "state": "NY",
      "postal_code": "10118",
      "country": "US"
    },
    "include_taxability_reason": true,
    "line_items": [
      {
        "id": "pro-plan-annual",
        "product_id": "pro-plan-annual",
        "amount": 120000
      },
      {
        "id": "extra-seat",
        "product_id": "extra-seat",
        "amount": 30000
      }
    ]
  }'
```

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):

```json theme={"dark"}
{
  "data": {
    "sphere_tax_calculation_id": "CALCULATION_ID",
    "lines": [
      {
        "id": "pro-plan-annual",
        "tax_amounts": [
          {
            "amount": 10650,
            "tax_rate": {
              "percentage": 8.875,
              "jurisdiction": "New York"
            }
          }
        ]
      },
      {
        "id": "extra-seat",
        "tax_amounts": [
          {
            "amount": 2662,
            "tax_rate": {
              "percentage": 8.875,
              "jurisdiction": "New York"
            }
          }
        ]
      }
    ]
  }
}
```

`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.

> [tab] Address known before checkout
>
> Calculate tax first (step 2), then [create the client session](https://primer.io/docs/api-reference/v2.4/api-reference/client-session-api/create-a-client-session.md) with the tax and the customer's address already in it:
>
> ```bash theme={"dark"}
> curl -X POST \
>   https://api.sandbox.primer.io/client-session \
>   -H "X-Api-Key: YOUR_API_KEY" \
>   -H "X-Api-Version: 2.4" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "orderId": "order-123",
>     "currencyCode": "USD",
>     "customerId": "customer-123",
>     "customer": {
>       "emailAddress": "customer@example.com",
>       "billingAddress": {
>         "addressLine1": "350 5th Ave",
>         "city": "New York",
>         "state": "NY",
>         "postalCode": "10118",
>         "countryCode": "US"
>       }
>     },
>     "order": {
>       "countryCode": "US",
>       "lineItems": [
>         {
>           "itemId": "pro-plan-annual",
>           "description": "Pro plan (annual)",
>           "amount": 120000,
>           "quantity": 1,
>           "taxAmount": 10650
>         },
>         {
>           "itemId": "extra-seat",
>           "description": "Extra seat (annual)",
>           "amount": 15000,
>           "quantity": 2,
>           "taxAmount": 2662
>         }
>       ]
>     }
>   }'
> ```
>
> 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.

> [tab] Address collected in checkout
>
> Create the client session as usual, with `taxAmount` set to `0` on each line item, because you don't have the address yet. Block payment until tax is calculated. For example, render Primer Checkout disabled, and handle `primer:payment-start` as shown in step 4.
>
> When the customer submits their address, your server calculates tax (step 2) and [updates the client session](https://primer.io/docs/api-reference/v2.4/api-reference/client-session-api/update-client-session.md) with the tax and the address:
>
> ```bash theme={"dark"}
> curl -X PATCH \
>   https://api.sandbox.primer.io/client-session \
>   -H "X-Api-Key: YOUR_API_KEY" \
>   -H "X-Api-Version: 2.4" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "clientToken": "YOUR_CLIENT_TOKEN",
>     "customer": {
>       "billingAddress": {
>         "addressLine1": "350 5th Ave",
>         "city": "New York",
>         "state": "NY",
>         "postalCode": "10118",
>         "countryCode": "US"
>       }
>     },
>     "order": {
>       "countryCode": "US",
>       "lineItems": [
>         {
>           "itemId": "pro-plan-annual",
>           "description": "Pro plan (annual)",
>           "amount": 120000,
>           "quantity": 1,
>           "taxAmount": 10650
>         },
>         {
>           "itemId": "extra-seat",
>           "description": "Extra seat (annual)",
>           "amount": 15000,
>           "quantity": 2,
>           "taxAmount": 2662
>         }
>       ]
>     }
>   }'
> ```
>
> > [!WARNING]
> >
> > `PATCH /client-session` replaces `order.lineItems` and `metadata` entirely. Always send the full list of line items and all of your metadata, including any keys your workflow conditions use. Otherwise, they're removed.
>
> In the browser, call [`primer.refreshSession()`](https://primer.io/docs/sdk/primer-checkout-web/events-reference#refreshsession) once your server responds. The pay button then shows the new total, including tax.
>
> ```js theme={"dark"}
> await fetch('/my-backend/calculate-tax', {
>   method: 'POST',
>   headers: { 'Content-Type': 'application/json' },
>   body: JSON.stringify({ address }),
> });
> await primer.refreshSession();
> ```
>
> If the order or the address changes, calculate tax again and update the session again.

**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`](https://primer.io/docs/sdk/primer-checkout-web/events-reference#primerpayment-start) as a guard: if tax wasn't calculated for the address currently on screen, abort the payment.

If you [fail open](#handle-sphere-being-unavailable) when Sphere is unavailable, let the payment continue in that case too. Otherwise the guard blocks every payment during an outage.

```js theme={"dark"}
const onPaymentStart = (e) => {
  e.preventDefault();
  const {
    continuePaymentCreation,
    abortPaymentCreation,
  } = e.detail;

  // Tax calculated for the address on screen, or
  // Sphere unavailable and you fail open?
  const address = currentAddress();
  const ready = taxIsCalculatedFor(address)
    || failingOpenFor(address);
  if (!ready) {
    showError('Recalculate tax for this address.');
    abortPaymentCreation();
    return;
  }

  attempt += 1;
  const idempotencyKey = `${orderId}:${attempt}`;
  continuePaymentCreation({ idempotencyKey });
};

checkout.addEventListener(
  'primer:payment-start',
  onPaymentStart,
);
```

Use a new [idempotency key](https://primer.io/docs/checkout/primer-checkout/guides-and-recipes/use-idempotency-keys.md) 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`](https://docs.getsphere.com/features/integrations/api/transaction-api/transactions).

Confirm the payment on your server first, rather than relying on the browser. Either listen for the [payment status webhook](https://primer.io/docs/api-reference/endpoints/v2.4/payment-webhooks/payment-status-update.md), or fetch the payment with [`GET /payments/{id}`](https://primer.io/docs/api-reference/v2.4/api-reference/payments-api/get-a-payment). 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](https://primer.io/docs/manage-payments/cancel-payment.md). Wait for the [payment status webhook](https://primer.io/docs/api-reference/endpoints/v2.4/payment-webhooks/payment-status-update.md) to report `SETTLED`.

```bash theme={"dark"}
curl -X POST \
  https://api.getsphere.com/v1/transactions \
  -H "X-API-KEY: YOUR_SPHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "order-123",
    "type": "debit",
    "status": "finalized",
    "finalized_on": "2026-11-02T11:51:33Z",
    "currency": "usd",
    "customer_id": "customer-123",
    "customer_email": "customer@example.com",
    "billing_address": {
      "address1": "350 5th Ave",
      "city": "New York",
      "state": "NY",
      "postal_code": "10118",
      "country": "US"
    },
    "sphere_tax_calculation_id": "CALCULATION_ID",
    "line_items": [
      {
        "external_id": "pro-plan-annual",
        "product_id": "pro-plan-annual",
        "amount": "1200.00",
        "quantity": "1",
        "unit_price": "1200.00"
      },
      {
        "external_id": "extra-seat",
        "product_id": "extra-seat",
        "amount": "300.00",
        "quantity": "2",
        "unit_price": "150.00"
      }
    ],
    "metadata": {
      "primerPaymentId": "YOUR_PAYMENT_ID"
    }
  }'
```

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](#handle-sphere-being-unavailable) 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"`).

> [!WARNING]
>
> **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](https://primer.io/docs/manage-payments/cancel-payment.md) 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`](https://github.com/primer-io/examples/blob/main/examples/sphere-tax/server/orders.js) checks the payment with `GET /payments/{id}` and queues the sale, which [`server/outbox.js`](https://github.com/primer-io/examples/blob/main/examples/sphere-tax/server/outbox.js) sends to Sphere.

**6. Record refunds as credit notes**

For each [refund](https://primer.io/docs/manage-payments/refund-payment.md), 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:

```bash theme={"dark"}
curl -X POST \
  https://api.getsphere.com/v1/transactions \
  -H "X-API-KEY: YOUR_SPHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "order-123-refund-1",
    "type": "credit",
    "status": "finalized",
    "original_transaction_id": "order-123",
    "finalized_on": "2026-11-03T09:12:00Z",
    "currency": "usd",
    "customer_id": "customer-123",
    "billing_address": {
      "address1": "350 5th Ave",
      "city": "New York",
      "state": "NY",
      "postal_code": "10118",
      "country": "US"
    },
    "line_items": [
      {
        "external_id": "pro-plan-annual",
        "product_id": "pro-plan-annual",
        "amount": "367.39"
      },
      {
        "external_id": "extra-seat",
        "product_id": "extra-seat",
        "amount": "91.85"
      }
    ]
  }'
```

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](https://primer.io/docs/api-reference/endpoints/v2.4/payment-webhooks/payment-refund.md) confirms the refund, rather than when the refund request returns.

In the example: `allocateRefund` in [`server/refunds.js`](https://github.com/primer-io/examples/blob/main/examples/sphere-tax/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](https://docs.getsphere.com/features/integrations/api/transaction-api/transactions).

## 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.

| | Fail open | Fail closed |
| - | - | - |
| What the customer sees | They pay the price without tax | They can't pay until tax is calculated |
| Effect on revenue | No lost sales | Lost sales while Sphere is unavailable |
| Effect on tax | You still owe the tax on the sale, but the customer didn't pay it. You pay it from the order's revenue. | The customer pays the tax, as usual |

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`](https://github.com/primer-io/examples/blob/main/examples/sphere-tax/server/sphere.js) decides when to fail open, and [`server/worker.js`](https://github.com/primer-io/examples/blob/main/examples/sphere-tax/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

| Error or symptom | Cause | Fix |
| - | - | - |
| `Tax calculation does not match these lines` | Line `external_id` values in the transaction don't match the line `id` values in the tax calculation | Use the same line ID in both calls |
| A retry after a declined payment fails with `IDEMPOTENCY_KEY_ALREADY_EXISTS` | The same idempotency key was reused | Use a new key for each payment attempt |
| A sale appears in the wrong tax period | `finalized_on` was missing, so a retry recorded the sale at the time of the retry | Set `finalized_on` to the payment date |

## 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](https://primer.io/docs/checkout/primer-checkout/guides-and-recipes/express-checkout-shipping.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.