> ## Documentation Index > Fetch the complete documentation index at: https://spidocs.chargebee.com/llms.txt > Use this file to discover all available pages before exploring further. # Check taxability > Checks whether the tax address is valid in terms of tax calculation. This endpoint checks whether the address information of the customer is sufficient for the tax provider to return a tax rate. It does not consider the nexus status of the merchant and is mandatory to integrate for the tax provider. ## OpenAPI ````yaml post /address/check-taxability openapi: 3.0.3 info: description: > ## Overview Tax Service Adapter is a Service Provider Interface (SPI) that helps Chargebee communicate with API platforms providing the following services: - Address validation - Estimating taxes for sales - Submitting invoices for tax filing If you have an API that provides the services mentioned above and want Chargebee to be able to integrate with it, you can build an adapter service according to this specification. ## Terminology Here's a list of terms we've used to describe this specification. ### Merchant Chargebee’s customer who is carrying out the business of selling products. Also known as the Seller. The Seller has one or more Chargebee accounts. ### Chargebee The SaaS which manages subscriptions and revenue operations on behalf of the Merchant. Chargebee makes API calls to the Tax Service Adapter for tax estimation and tax filing of transactions between the Merchant and the Customer. ### Customer Merchant’s customer who purchases products from the Merchant. Their customer record(s) and other details are stored within Chargebee under the Merchant’s account. ### Tax Authority The institution, usually a government, that is responsible for collecting taxes for commercial transactions between Merchants and their Customers. ### Tax Service Provider The service which provides tax estimation and tax filing services for merchants. ### Tax Service Adapter The SPI for which the spec is defined in this document. This adapter serves the following purposes: - Translates API requests (as defined in this document) from Chargebee to the request format specified by the Tax Service Provider's API. - Translates API responses from the Tax Service Provider APIs to the format understood by Chargebee (as defined in this document). ### Authorization Chargebee uses HTTP header-based authorization for all the API endpoints associated with Tax Service Adapter. We dynamically pass this authorization key in the HTTP header. The parameter that holds this key is found in the JSON object `api_configuration` required for configuring your onboarding on Chargebee's marketplace. In the `api_configuration` object, our [Taxes Service Adapter SPI](https://chargebee.atlassian.net/l/cp/ca5aZ1mA) checks the authorization key parameter from `credential_configuration.id` and creates the HTTP header-based input query parameter for authorization. The `credential_configuration` is an array of objects with an `id` attribute, and the value of `id` is the parameter containing the authorization key. Following are the JSON snippets for your reference. ```json "api_configuration": { "api_base_url": "https://xyz.abc.com/chargebee", "credential_configuration": [ { "id":"authorization_key", "name": "Authorization Key", "type": "text", "is_sensitive": true }, { "id": "client_secret", "name": "Client Secret", "type": "text", "is_sensitive": true } ] } ``` `"Authorization":"{"":"test_GykCvTykZFTBqHQAFzjMN9R1Thgdho0Q"}"` title: Taxes Service Adapter SPI version: 0.3.7 servers: - description: Production SPI server. url: https://rest.taxes.provider.com/api/v1 - description: Sandbox SPI server. url: https://sandbox.taxes.provider.com/api/v1 security: - Authorization: [] tags: - description: Endpoints to validate an address and check its taxability. name: Address - description: Endpoints to estimate taxes. name: TaxEstimate - description: Endpoints to manage invoices sent to the Tax Service Provider. name: Invoice - description: Endpoints to manage credit notes sent to the Tax Service Provider. name: CreditNote - description: >- Endpoints to validate the credentials used for calling the Tax Service Adapter. name: Authentication - description: >- Endpoints to monitor the health of the Tax Service Provider and the Tax Service Adapter. name: Health paths: /address/check-taxability: post: tags: - Address summary: Check taxability description: >- Checks whether the tax address is valid in terms of tax calculation. This endpoint checks whether the address information of the customer is sufficient for the tax provider to return a tax rate. It does not consider the nexus status of the merchant and is mandatory to integrate for the tax provider. operationId: checkAddressTaxability parameters: - description: Merchant's domain name will be sent by Chargebee in: header name: merchant_id required: false schema: type: string - description: Unique id of the request will be sent by Chargebee in: header name: trace_id required: false schema: type: string requestBody: content: application/json: examples: CheckAddressTaxabilityValidRequest-Option1: $ref: >- #/components/examples/CheckAddressTaxabilityValidRequest-Option1 CheckAddressTaxabilityInvalidRequest-Option1: $ref: >- #/components/examples/CheckAddressTaxabilityInvalidRequest-Option1 CheckAddressTaxabilityValidRequest-Option2: $ref: >- #/components/examples/CheckAddressTaxabilityValidRequest-Option2 CheckAddressTaxabilityInvalidRequest-Option2: $ref: >- #/components/examples/CheckAddressTaxabilityInvalidRequest-Option2 CheckAddressTaxabilityValidRequest-Option3: $ref: >- #/components/examples/CheckAddressTaxabilityValidRequest-Option3 CheckAddressTaxabilityInvalidRequest-Option3: $ref: >- #/components/examples/CheckAddressTaxabilityInvalidRequest-Option3 schema: $ref: '#/components/schemas/CheckAddressTaxabilityRequest' responses: '200': content: application/json: examples: CheckAddressTaxabilityValidResponse-Option1: $ref: >- #/components/examples/CheckAddressTaxabilityValidResponse-Option1 CheckAddressTaxabilityInvalidResponse-Option1: $ref: >- #/components/examples/CheckAddressTaxabilityInvalidResponse-Option1 CheckAddressTaxabilityValidResponse-Option2: $ref: >- #/components/examples/CheckAddressTaxabilityValidResponse-Option2 CheckAddressTaxabilityInvalidResponse-Option2: $ref: >- #/components/examples/CheckAddressTaxabilityInvalidResponse-Option2 CheckAddressTaxabilityValidResponse-Option3: $ref: >- #/components/examples/CheckAddressTaxabilityValidResponse-Option3 CheckAddressTaxabilityInvalidResponse-Option3: $ref: >- #/components/examples/CheckAddressTaxabilityInvalidResponse-Option3 schema: $ref: '#/components/schemas/CheckAddressTaxabilityResponse' description: Tax can be calculated for the address provided. '400': content: application/json: example: errors: - code: INVALID_DATA message: Empty address provided. entity: Address schema: $ref: '#/components/schemas/ValidationErrorResponse' description: Bad request. '401': description: Unauthenticated request. '403': description: Unauthorized request. '429': description: Too many requests. '500': content: application/json: examples: Error500: $ref: '#/components/examples/Error500Response' schema: $ref: '#/components/schemas/BasicErrorResponse' description: Unexpected error while processing request. '503': content: application/json: example: status: DOWN version: 1.0.0 description: The service is unhealthy. Several components are down. components: - id: app-db-memory name: Application Database Memory Usage type: DATABASE status: UP - id: adapter-server name: Adapter API Server type: ADAPTER status: DOWN - id: service-server name: API Server type: API status: DOWN time: '2022-11-01T05:12:08.131Z' schema: $ref: '#/components/schemas/HealthCheckResponse' description: Service is unhealthy. components: examples: CheckAddressTaxabilityValidRequest-Option1: description: >- Taxable address with combination of city,state,country,postalCode sent in a post request summary: Taxable address request (city + state + country + postalCode) value: address: line1: '' line2: '' line3: '' city: IRVINE state: CA country: US postalCode: '92614' CheckAddressTaxabilityInvalidRequest-Option1: description: >- Non-taxable address with combination of city,state,country,postalCode sent in a post request summary: Non-taxable address request (city + state + country + postalCode) value: address: line1: '' line2: '' line3: '' city: Irvine state: CA country: US postalCode: '88777' CheckAddressTaxabilityValidRequest-Option2: description: >- Taxable address with combination of city,country,postalCode sent in a post request summary: Taxable address request (city + country + postalCode) value: address: line1: '' line2: '' line3: '' state: '' city: Irvine country: US postalCode: '92615' CheckAddressTaxabilityInvalidRequest-Option2: description: Shows a non-taxable address sent in a post request summary: Non-taxable address request (city + country + postalCode) value: address: line1: '' line2: '' line3: '' state: '' city: Irvine country: US postalCode: '83835' CheckAddressTaxabilityValidRequest-Option3: description: >- Taxable address with combination of city,state,postalCode sent in a post request summary: Taxable address request (postalCode) value: address: line1: '' line2: '' line3: '' city: '' state: '' country: '' postalCode: '92614' CheckAddressTaxabilityInvalidRequest-Option3: description: >- Non-taxable address with combination of city,state,postalCode sent in a post request summary: Non-taxable address request (postalCode) value: address: line1: '' line2: '' line3: '' city: '' state: '' country: '' postalCode: '45645' CheckAddressTaxabilityValidResponse-Option1: description: >- Valid Response based on combination of city,state,country,postalCode sent in a post request summary: Taxable address Response (city + state + country + postalCode) value: isTaxable: true CheckAddressTaxabilityInvalidResponse-Option1: description: >- Invalid Response based on combination of city,state,country,postalCode sent in a post request summary: Non-taxable address Response (city + state + country + postalCode) value: isTaxable: false CheckAddressTaxabilityValidResponse-Option2: description: >- Valid Response based on combination of city,country,postalCode sent in a post request summary: Taxable address response (city + country + postalCode) value: isTaxable: true CheckAddressTaxabilityInvalidResponse-Option2: description: >- Invalid response based on combination of city,country,postalCode sent in a post request summary: Non-taxable address response (city + country + postalCode) value: isTaxable: false CheckAddressTaxabilityValidResponse-Option3: description: >- Valid response based on combination of city,state,postalCode sent in a post request summary: Taxable address response (postalCode) value: isTaxable: true CheckAddressTaxabilityInvalidResponse-Option3: description: >- Non-taxable address response based on combination of city,state,postalCode sent in a post request summary: Non-taxable address response (postalCode) value: isTaxable: false Error500Response: description: Unexpected error during processing the request. summary: Unexpected error. value: message: Unexpected error during processing the request. schemas: CheckAddressTaxabilityRequest: additionalProperties: false description: >- The taxability request containing the address. Postal code & Country is mandatory. example: address: country: country city: city postalCode: postalCode state: state line3: line3 line2: line2 line1: line1 properties: address: $ref: '#/components/schemas/Address' type: object CheckAddressTaxabilityResponse: example: isTaxable: true properties: isTaxable: description: The taxability of the address. type: boolean required: - isTaxable type: object ValidationErrorResponse: description: >- The error response for validation errors with the respective entity and its field information. properties: errors: items: $ref: '#/components/schemas/ValidationErrorResponse_errors_inner' type: array required: - errors type: object BasicErrorResponse: additionalProperties: false description: >- The basic error response containing the error message and the help documentation link. properties: message: description: The description of the error with details about it's cause. example: Invalid Credentials maxLength: 250 type: string helpUrl: description: >- The link to the documentation for more information about the error and the corrective action. example: https://apidocs.chargebee.com#Authentication format: uri type: string required: - message type: object HealthCheckResponse: example: components: - endpoints: - endpoints - endpoints name: name description: description id: id type: OTHER status: null - endpoints: - endpoints - endpoints name: name description: description id: id type: OTHER status: null description: description time: '2000-01-23T04:56:07.000Z' version: version status: null properties: version: minLength: 1 type: string description: description: >- The description of the health status returned by the Service Adapter. maxLength: 250 type: string status: $ref: '#/components/schemas/HealthStatus' components: description: >- List of health status details for each component reported by the Service Adapter. items: $ref: '#/components/schemas/HealthCheckComponent' type: array time: description: The timestamp of the health status reported by the Service Adapter. format: date-time type: string required: - components - status - time type: object Address: description: Represents the address used for validation. example: country: country city: city postalCode: postalCode state: state line3: line3 line2: line2 line1: line1 properties: line1: description: First line of the street address maxLength: 180 type: string line2: description: Second line of the street address maxLength: 150 type: string line3: description: Third line of the street address maxLength: 150 type: string city: description: The city of the address maxLength: 50 type: string state: description: >- The state of the address following the ISO 3166-2 state/province code without the country prefix. maxLength: 50 type: string postalCode: description: Postal Code / Zip Code of the address. maxLength: 20 type: string country: description: >- The country of the address following the ISO 3166-1 alpha-2 standard. maxLength: 2 type: string type: object ValidationErrorResponse_errors_inner: properties: entity: description: The target entity that has the invalid field or value. example: customer maxLength: 20 type: string entityField: description: The field of an entity that has the invalid value. example: lineItems[0].taxIdentifiers[0].value maxLength: 250 type: string code: $ref: '#/components/schemas/ErrorCode' message: description: A short message describing the reason for the error. example: Invalid tax code provided. maxLength: 250 type: string helpUrl: description: >- The link to the documentation for more information about the error and the corrective action. example: https://apidocs.chargebee.com#Authentication format: uri type: string required: - code - message type: object HealthStatus: description: The status of a specific component reported by the Service Adapter. enum: - UP - DOWN - WARN type: string HealthCheckComponent: description: >- The health status details of a specific component reported by the Service Adapter. example: endpoints: - endpoints - endpoints name: name description: description id: id type: OTHER status: null properties: id: description: The id of the component. maxLength: 50 type: string name: description: The name of the component. maxLength: 150 type: string type: description: > The type of component affected when `status` is `WARN` or `DOWN`. The possible values are: - `ADAPTER`: The reported status is for the Service Adapter. - `API`: The reported status is for the Service Provider. - `DATABASE`: The reported status is for a database dependency of the Service Provider. - `SYSTEM`: The reported status is for any other known system component such as cache or gateway. - `OTHER`: The reported status is either for a component that does not belong to the types described above or the source of the issue is unknown. enum: - OTHER - SYSTEM - API - ADAPTER - DATABASE type: string description: description: The detailed status of the component. maxLength: 250 type: string status: $ref: '#/components/schemas/HealthStatus' endpoints: description: >- When the `status` of the component is not `UP`, then the list of endpoints affected. items: type: string type: array required: - id - name - status - type type: object ErrorCode: description: >- The error codes classify the type of exception that occurred during processing the request. enum: - INVALID_OPERATION - SERVICE_EXCEPTION - SERVICE_UNAVAILABLE - SERVICE_LIMIT_EXCEEDED - MISSING_REQUIRED_DATA - INVALID_DATA - INVALID_TYPE - INVALID_FORMAT - INVALID_RANGE - LOCATION_VALIDATION_FAILED type: string securitySchemes: Authorization: description: >- The json of all the parameters specified in authentication configuration of tax app will be sent by Chargebee. in: header name: Authorization type: apiKey ````