Skip to main content

​
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 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. Find instructions on Sphere’s website here.

​
Connecting your account

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

​
Sample request and response payload

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.

​
Request (Orb → Sphere)

{
  "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)

{
  "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 handlesvoid_tax(...) by receiving updates about invoices and credit notes via webhook, on its own asynchronous schedule.