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

# Sphere

# About

## **Provider-specific behaviors**

* Unlike other tax integrations, you don't need to map Items in Orb to Products in Sphere — Sphere automatically pulls Items from Orb.

## **Geographic coverage**

100+ countries; all US states.

# Setup

## **Prerequisites**

1. A Sphere account (sign up at [<u>auth.getsphere.com/en/signup</u>](http://auth.getsphere.com/en/signup) if you don't have one).
2. You need to enable the Orb integration on the Integrations page of your Sphere account. [<u>Find instructions on Sphere’s website here</u>](https://docs.getsphere.com/features/integrations/prebuilt-connectors/orb-integration).

## **Connecting your account**

1. Navigate to **Settings > Taxes**.
2. Select “Connect to Sphere.”
3. Enter your Sphere API key.

# **Sample request and response payload**

<Info>
  *The example below is illustrative of the shape Orb sends to and receives from Sphere today, based on Orb's tax provider processors and test fixtures. Exact field names and structure can change as Sphere versions its API — confirm against current behavior before relying on it for integration work.*
</Info>

### ***Request (Orb → Sphere)***

```text theme={null}
{
  "transaction_id": "<invoice_id>",
  "transaction_type": "invoice",
  "customer": {
    "id": "<customer_id>",
    "address": {
      "address1": "<line1>",
      "address2": "<line2>",
      "city": "<city>",
      "state": "<state>",
      "postal_code": "<postal_code>",
      "country": "<country>"
    },
    "tax_id": "<tax_id_or_null>",
    "metadata": {}
  },
  "currency": "usd",
  "line_items": [
    {
      "id": "<invoice_line_item_id>",
      "amount": 10000,
      "product_id": "<item_id>"
    }
  ]
}
```

### ***Response (Sphere → Orb)***

```text theme={null}
{
  "transaction_id": "invoice-123",
  "lines": [
    {
      "id": "line-item-123",
      "tax_amounts": [
        {
          "amount": 1000,
          "tax_rate": {
            "display_name": "<tax name>",
            "percentage": 10,
            "taxability_reason": null
          }
        }
      ]
    }
  ]
}
```

## **Reporting tax for filing**

Sphere is the one integration without a separate reporting or commit call.

Orb's `report_tax(invoice)` for Sphere just calls the same `fetch_tax(invoice)` used for calculation.  Sphere handles`void_tax(...)` by receiving updates about invoices and credit notes via webhook, on its own asynchronous schedule.