Tax Calculation

Details on our real-time tax calculation API as well as error codes and messages are provided below.

Prerequisites

1. A Sphere account is required. Please contact the Sphere sales team for access (you can either book a consult here or email our CEO directly at [e-mail])

2. After logging in, navigate to the Products section and ensure that the products in your billing system are listed in the Products table.

   1. Note: To populate the Products tab, you must first connect a billing provider in the Sphere app (via the Integrations section of the app). This connection will automatically retrieve and display the products from your billing provider.

3. Verify that each Product has an assigned Product Tax Code, which is used to determine the taxability of your product around the world (refer to Tax Determination section).

   1. Note: If the you don't assign Product Tax Codes to your products and you include product IDs in the payload sent to the Sphere Tax Calculation API, the API will respond with a 400 Bad Request error.

4. Make sure you are registered with the appropriate tax authority in Sphere (via the Registrations section of the app) for the customer address you plan to provide, and verify that the tax calculation toggle is switched on in the relevant Region page (refer to Autofiling and Tax Calculations section).

   1. Note: If you are not registered with a tax authority or the tax calculation toggle is switched off, the API will return empty tax_amounts arrays for line items. (See API Response section below)

---

Endpoint

• URL: https://server.getsphere.com/tax_api/calculate_tax

• Method: POST

---

Authentication

To access this endpoint, you need an API key, which must be provided in the request header.

• Header Key: X-API-KEY

• Header Value: YOUR_API_KEY

---

Request Payload

1. customer_address (object, required): Contains the customer’s address details for tax calculation.

• address1 (string, optional): First line of the address.

• address2 (string, optional): Second line of the address.

• city (string, required): City name.

• state (string, optional): State or region.

• postal_code (string, required): Postal or ZIP code.

• country (string, required): Country name.

2. line_items (array of objects, required): A list of items for which tax needs to be calculated.

Each item includes:

• amount (integer, required): The item’s price in cents (e.g., 10000 for $100.00).

• product_id (string, required): Unique identifier for the product. This id has already been defined in Sphere (under the Products tab). It’s important to note that this represents the product’s ID within the billing platform. For example, if Stripe is used, the ID might look like prod_ABC123.

• discount_amount (integer, optional, default 0): Discount applied to the item in cents.

• tax_inclusive (boolean, optional, default false): Indicates if the item price includes tax.

3. currency (string, required): The currency code (ISO 4217 format) in which the amounts are specified. For example: “usd”. Note: Only lowercase currency codes are accepted.

Request Structure

The request should be in JSON format. Here is a sample request payload:

{
  "customer_address": {
    "address1": "Investors Boulevard",
    "city": "Myrtle Beach",
    "state": "SC",
    "postal_code": "29579",
    "country": "US"
  },
  "line_items": [
    {
      "amount": 10000,
      "product_id": "prod_RArEhwhXLfX5jF",
      "discount_amount": 0,
      "tax_inclusive": false
    }
  ],
  "currency": "usd"
}

---

API Response

• lines (array): Contains tax information for each line item.

  • id (string): Product ID of the line item.

  • tax_amounts (array): A list of taxes applied to the line item.

    • amount (integer): Tax amount in cents for this specific tax.

    • taxable_amount (integer): Amount subject to the tax in cents.

    • tax_rate (object): Details of the tax rate applied.

      • percentage (float): Tax rate as a percentage.

      • inclusive (boolean): Indicates if the tax is inclusive.

      • display_name (string): Name of the tax (e.g., “Tourism Development Tax”).

      • jurisdiction (string): The tax jurisdiction (e.g., “Myrtle Beach”).

      • country (string): Country code (e.g., “US”).

      • state (string): State or region code (e.g., “SC”).

• sphere_tax_calculation_id (string): Unique identifier for the tax calculation request.

Response Structure

The API will respond with a 200 status code and return the calculated tax details for each line item, along with a unique Sphere tax calculation ID. Here is a sample response:

{
  "lines": [
    {
      "id": "prod_RArEhwhXLfX5jF",
      "tax_amounts": [
        {
          "amount": 900,
          "taxable_amount": 10000,
          "tax_rate": {
            "percentage": 9.0,
            "inclusive": false,
            "display_name": "South Carolina",
            "jurisdiction": "South Carolina",
            "country": "US",
            "state": "SC"
          }
        }
      ]
    }
  ],
  "sphere_tax_calculation_id": "cfd1e35a-ccb8-4bf1-86ed-49e332be220b"
}

---

Error Codes and Messages

When calling the Sphere Tax Calculation API, you may encounter the following error responses. These error codes indicate specific issues with the data provided in the request.

1. Unauthorized Access

{
  "type": "api_error",
  "code": "unauthorized_access"
}

• Description: This error occurs when the API key provided in the request header is either missing or invalid, resulting in denied access to the Sphere Tax Calculation API.

• Resolution: Verify that the API key is correctly included in the request headers. Ensure the key is correct, active, and authorized for this endpoint.

2. Invalid Customer Tax Location

{
  "type": "api_error",
  "code": "customer_tax_location_invalid",
  "message": "The customer address is either invalid or incomplete."
}

• Description: This error occurs when the customer’s address information in the request payload is incomplete or invalid. Ensure that the address fields, particularly address1, city, state, postal_code, and country, are correctly populated and valid.

• Resolution: Verify the address information and resend the request.

3. Invalid Product Tax Code

{
  "type": "api_error",
  "code": "invalid_product_tax_code",
  "message": "One or more products are missing a tax code assignment in Sphere. Please ensure all products have a tax code to proceed."
}

• Description: This error indicates that one or more products listed in the line_items array lack a tax code assignment in Sphere. Tax codes are required to calculate the appropriate tax rates for each product.

• Resolution: Review the products in the line_items section, and make sure each has a valid tax code assigned in Sphere. Once the missing tax codes are added, retry the request.

4. Too Many Requests

{
  "type": "api_error",
  "code": "too_many_requests"
}

• Description: This error indicates that the client has exceeded the maximum number of requests allowed within a specific time frame. The Sphere API enforces rate limits to prevent overloading and ensure fair access.

• Resolution: Pause requests temporarily to allow the rate limit to reset. You may need to wait several minutes before retrying. If you frequently encounter this error, consider adjusting the frequency of requests or contacting Sphere support to discuss rate limit options.