# Tax Calculation ## **Prerequisites** 1. A Sphere account is required. Please contact the Sphere sales team for access (you can either book a consult [here](https://calendly.com/d/44n-bjc-wq7/meeting-with-sphere-team) or email our CEO directly at ) 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](/features/calculation.md#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](/features/registration.md) 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](/features/registration.md#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](/features/integrations/api/tax-calculation.md#api-response) section below) *** ## Endpoint * **URL:** * **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\_id** (string, optional): Represents the customer’s identifier in the billing platform (e.g., cus\_ABC123 for Stripe). **2. 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. **3. line\_items (array of objects, required):** A list of items for which tax needs to be calculated. Each item includes: * **id** (string, optional): A unique identifier for the line item in your system (e.g., `line_item_1`). If provided, it will also be included in the API response. * **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. **4. 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: ```json { "customer_id": "cus_RQx5PQDFSMH6Ku", "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): If a line item ID was included in the request payload, it will be returned here. Otherwise, the product ID will be used as the line item’s ID. * **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”). * **tax\_type** (string): One of: * sales\_tax * gst * hst * pst * qst * lease\_tax * amusement\_tax * vat * jct * communications\_tax * igst * retail\_delivery\_fee * rst * service\_tax * **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: ```json { "message": "Tax calculated successfully", "data": { "lines": [ { "id": "prod_RArEhwhXLfX5jF", "tax_amounts": [ { "amount": 900, "taxable_amount": 10000, "tax_rate": { "percentage": 9.0, "inclusive": false, "display_name": "Sales Tax", "jurisdiction": "South Carolina", "country": "US", "state": "SC", "tax_type": "sales_tax" } } ] } ], "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** ```json { "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** ```json { "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** ```json { "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** ```json { "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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.getsphere.com/features/integrations/api/tax-calculation.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.