API Reference: Tax Service Adapter

Tax Service Adapter is a Service Provider Interface (SPI) that helps Chargebee communicate with API platforms that provide 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 the specification given below.

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":"{"<authorization_key>":"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: - bearerAuth: [] - apiKey: [] 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: /health: get: description: >- This endpoint is used to fetch the health status of the Service Provider. operationId: fetchHealth responses: '200': content: application/json: example: status: UP version: 1.0.0 description: The service is healthy. components: - id: app-db-memory name: Application Database type: DATABASE status: UP - id: adapter-server name: Adapter API Server type: ADAPTER status: UP - id: service-server name: API Server type: API status: UP time: 2022-11-01T05:12:08.131Z schema: $ref: '#/components/schemas/HealthCheckResponse' description: Service is healthy. '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. security: - {} summary: Fetch the health status of the Service Provider. tags: - Health x-accepts: application/json /credentials/validate: post: description: >- This endpoint is used to validate the credentials used to call the Service Provider. operationId: validateCredentials responses: '200': content: application/json: example: status: VALID schema: $ref: '#/components/schemas/CredentialValidationResponse' description: Authentication succeeded. '401': content: application/json: example: status: INVALID schema: $ref: '#/components/schemas/CredentialValidationResponse' description: Authentication failed. '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. summary: Validate credentials tags: - Authentication x-accepts: application/json /tax-estimate: post: description: >- This endpoint is used to estimate taxes for a set of line items being sold by the Merchant to a Customer. operationId: estimateTaxes requestBody: content: application/json: examples: TaxEstimationRequestSimple: $ref: '#/components/examples/TaxEstimationRequestSimple' TaxEstimationRequestWithTaxInclusive: $ref: '#/components/examples/TaxEstimationRequestWithTaxInclusive' TaxEstimationRequestWithLineItemDiscount: $ref: '#/components/examples/TaxEstimationRequestWithLineItemDiscount' TaxEstimationRequestWithCustomerExemption: $ref: >- #/components/examples/TaxEstimationRequestWithCustomerExemption schema: $ref: '#/components/schemas/TaxEstimationRequest' responses: '200': content: application/json: examples: TaxEstimationResponseSimple: $ref: '#/components/examples/TaxEstimationResponseSimple' TaxEstimationResponseWithTaxInclusive: $ref: '#/components/examples/TaxEstimationResponseWithTaxInclusive' TaxEstimationResponseWithLineItemDiscount: $ref: >- #/components/examples/TaxEstimationResponseWithLineItemDiscount TaxEstimationResponseWithCustomerExemption: $ref: >- #/components/examples/TaxEstimationResponseWithCustomerExemption schema: $ref: '#/components/schemas/TaxEstimationResponse' description: Tax estimated successfully for given line items. '400': content: application/json: examples: Error400ResponseInvalidTaxCode: $ref: '#/components/examples/Error400ResponseInvalidTaxCode' Error400ResponseMissingCustomerAddress: $ref: '#/components/examples/Error400ResponseMissingCustomerAddress' schema: $ref: '#/components/schemas/ValidationErrorResponse' description: Bad request. '401': description: Unauthenticated request. '403': description: Unauthorized request. '404': description: Not found. '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. summary: Estimate tax tags: - TaxEstimate x-content-type: application/json x-accepts: application/json /invoices: post: description: >- This endpoint is used to send an invoice to the Tax Service Provider. Invoices created in Chargebee are statements of amounts owed by the Customer to the Merchant for a specific purchase. operationId: createInvoice requestBody: content: application/json: examples: InvoiceRequestSimple: $ref: '#/components/examples/InvoiceRequestSimple' InvoiceRequestWithTaxInclusive: $ref: '#/components/examples/InvoiceRequestWithTaxInclusive' schema: $ref: '#/components/schemas/InvoiceRequest' responses: '201': content: application/json: examples: InvoiceResponseSimple: $ref: '#/components/examples/InvoiceResponseSimple' InvoiceResponseWithTaxInclusive: $ref: '#/components/examples/InvoiceResponseWithTaxInclusive' schema: $ref: '#/components/schemas/Invoice' description: Invoice created successfully. '400': content: application/json: examples: Error400ResponseInvalidTaxCode: $ref: '#/components/examples/Error400ResponseInvalidTaxCode' Error400ResponseMissingCustomerAddress: $ref: '#/components/examples/Error400ResponseMissingCustomerAddress' 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. summary: Create Invoice tags: - Invoice x-content-type: application/json x-accepts: application/json '/invoices/{invoiceId}': get: description: This endpoint is used to retrieve an invoice for a given invoice id. operationId: fetchInvoice parameters: - description: >- The unique identifier of the invoice at the Tax Service Adapter or Tax Service Provider. explode: false in: path name: invoiceId required: true schema: type: string style: simple responses: '200': content: application/json: schema: $ref: '#/components/schemas/Invoice' description: Invoice retrieved successfully. '401': description: Unauthenticated request. '403': description: Unauthorized request. '404': description: Not found. '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. summary: Retrieve Invoice tags: - Invoice x-accepts: application/json '/invoices/{invoiceId}/commit': post: description: >- This endpoint is used to commit an invoice for a given invoice id. Once committed, the invoice is considered to be finalized. operationId: commitInvoice parameters: - description: >- The unique identifier of the invoice at the Tax Service Adapter or Tax Service Provider. explode: false in: path name: invoiceId required: true schema: type: string style: simple responses: '204': description: Invoice committed successfully. '401': description: Unauthenticated request. '403': description: Unauthorized request. '404': description: Not found. '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. summary: Commit Invoice tags: - Invoice x-accepts: application/json '/invoices/{invoiceId}/void': post: description: >- This endpoint is used to mark a specific invoice as void. Voiding cancels the invoice without deleting it. operationId: voidInvoice parameters: - description: >- The unique identifier of the invoice at the Tax Service Adapter or Tax Service Provider. explode: false in: path name: invoiceId required: true schema: type: string style: simple responses: '204': description: Invoice voided successfully. '401': description: Unauthenticated request. '403': description: Unauthorized request. '404': description: Not found. '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. summary: Void Invoice tags: - Invoice x-accepts: application/json /credit-notes: post: description: >- This endpoint is used to send a credit note to the Tax Service Adapter. A credit note is used to reduce the amount due on an invoice. If the credit note is issued after payments have been made for the invoice, refunds can be issued to the Customer. operationId: createCreditNote requestBody: content: application/json: examples: CreditNoteRequestFull: $ref: '#/components/examples/CreditNoteRequestFull' CreditNoteRequestFullWithTaxInclusive: $ref: '#/components/examples/CreditNoteRequestFullWithTaxInclusive' schema: $ref: '#/components/schemas/CreditNoteRequest' responses: '201': content: application/json: examples: CreditNoteResponseFull: $ref: '#/components/examples/CreditNoteResponseFull' CreditNoteResponseFullWithTaxInclusive: $ref: '#/components/examples/CreditNoteResponseFullWithTaxInclusive' schema: $ref: '#/components/schemas/CreditNote' description: Credit note created successfully. '400': content: application/json: examples: Error400ResponseInvalidCreditNoteId: $ref: '#/components/examples/Error400ResponseInvalidCreditNoteId' Error400ResponseMissingCustomerAddress: $ref: '#/components/examples/Error400ResponseMissingCustomerAddress' 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. summary: Create credit note tags: - CreditNote x-content-type: application/json x-accepts: application/json '/credit-notes/{creditNoteId}': get: description: >- This endpoint is used to retrieve a specific credit note using the unique credit note id. operationId: fetchCreditNote parameters: - description: >- The unique identifier of the credit note at the Tax Service Adapter or Tax Service Provider. explode: false in: path name: creditNoteId required: true schema: type: string style: simple - description: >- The unique identifier of the invoice at the Tax Service Adapter or Tax Service Provider. explode: true in: query name: invoiceId required: false schema: type: string style: form responses: '200': content: application/json: schema: $ref: '#/components/schemas/CreditNote' description: Credit note retrieved successfully. '401': description: Unauthenticated request. '403': description: Unauthorized request. '404': description: Not found. '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. summary: Retrieve credit note tags: - CreditNote x-accepts: application/json '/credit-notes/{creditNoteId}/commit': post: description: >- This endpoint is used to mark a credit note as committed. Once committed, the credit note is considered as finalized. operationId: commitCreditNote parameters: - description: >- The unique identifier of the credit note at the Tax Service Adapter or Tax Service Provider. explode: false in: path name: creditNoteId required: true schema: type: string style: simple - description: >- The unique identifier of the invoice at the Tax Service Adapter or Tax Service Provider. explode: true in: query name: invoiceId required: false schema: type: string style: form responses: '204': description: Credit note committed successfully. '401': description: Unauthenticated request. '403': description: Unauthorized request. '404': description: Not found. '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. summary: Commit credit note tags: - CreditNote x-accepts: application/json '/credit-notes/{creditNoteId}/void': post: description: >- This endpoint is used to void the credit note for a specific credit note id. Voiding reverses the credit note, thereby restoring the amount due on the invoice. operationId: voidCreditNote parameters: - description: >- The unique identifier of the credit note at the Tax Service Adapter or Tax Service Provider. explode: false in: path name: creditNoteId required: true schema: type: string style: simple - description: >- The unique identifier of the invoice at the Tax Service Adapter or Tax Service Provider. explode: true in: query name: invoiceId required: false schema: type: string style: form responses: '204': description: Credit note voided successfully. '401': description: Unauthenticated request. '403': description: Unauthorized request. '404': description: Not found. '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. summary: Void credit note tags: - CreditNote x-accepts: application/json /address/validate: post: description: >- Checks whether a given address is a valid delivery address for shipping purposes. The tax provider can decide whether to mention the full or valid address depending on their requirement. operationId: validateAddress requestBody: content: application/json: examples: AddressValidationValidRequest: $ref: '#/components/examples/AddressValidationValidRequest' AddressValidationInvalidRequest: $ref: '#/components/examples/AddressValidationInvalidRequest' schema: $ref: '#/components/schemas/AddressValidationRequest' responses: '200': content: application/json: examples: AddressValidationValidResponse: $ref: '#/components/examples/AddressValidationValidResponse' AddressValidationInvalidResponse: $ref: '#/components/examples/AddressValidationInvalidResponse' schema: $ref: '#/components/schemas/AddressValidationResponse' description: Address is validated successfully '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. summary: Address validation tags: - Address x-content-type: application/json x-accepts: application/json /address/check-taxability: post: 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 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. summary: Check taxability tags: - Address x-content-type: application/json x-accepts: application/json components: examples: TaxEstimationRequestSimple: description: A sample tax estimation request. value: seller: address: line1: 412 63rd South Avenue city: Baltimore state: MD country: US postalCode: '21230' customer: name: John Doe customerCode: customer_test address: line1: '59, Starlight Avenue' city: Newark state: NJ country: US postalCode: '98712' estimateDateTime: 2022-11-01T05:12:08.131Z currency: USD lineItems: - number: 1 itemCode: cbWatch description: A winding watch. quantity: 1 amount: 100 isTaxInclusive: false taxIdentifiers: - id: taxCode value: PT12312 TaxEstimationResponseSimple: description: A sample response to the tax estimation request. value: seller: address: line1: 412 63rd South Avenue city: Baltimore state: MD country: US postalCode: '21230' hasNexus: true customer: customerCode: customer_test address: line1: '59, Starlight Avenue' city: Newark state: NJ country: US postalCode: '98712' estimateDateTime: 2022-11-01T05:12:08.131Z currency: USD discountAmount: 0 subtotal: 100 exemptAmount: 0 taxableAmount: 100 taxAmount: 15 total: 115 lineItems: - number: 1 itemCode: cbWatch description: A winding watch. quantity: 1 amount: 100 isTaxInclusive: false isTaxable: true taxIdentifiers: - id: taxCode value: PT12312 discountAmount: 0 subtotal: 100 exemptAmount: 0 taxableAmount: 100 taxAmount: 15 total: 115 taxes: - number: 1 jurisdiction: code: '48' type: STATE name: CALIFORNIA name: SALE rate: 5 taxableAmount: 100 taxAmount: 5 - number: 2 jurisdiction: code: '27000' type: CITY name: SAN FRANCISCO name: SALE rate: 10 taxableAmount: 100 taxAmount: 10 TaxEstimationRequestWithTaxInclusive: description: A sample tax estimation request with tax inclusive. value: seller: address: line1: 412 63rd South Avenue city: Baltimore state: MD country: US postalCode: '21230' customer: name: John Doe customerCode: customer_test address: line1: 20 W 34th St city: New York state: NY country: US postalCode: '10001' estimateDateTime: 2022-11-01T05:12:08.131Z currency: USD lineItems: - number: 1 itemCode: cbWatch description: A winding watch. quantity: 1 amount: 100 isTaxInclusive: true taxIdentifiers: - id: taxCode value: PT12312 TaxEstimationResponseWithTaxInclusive: description: A sample response to the tax estimation request with tax inclusive. value: seller: address: line1: 412 63rd South Avenue city: Baltimore state: MD country: US postalCode: '21230' hasNexus: true customer: name: John Doe customerCode: customer_test address: line1: 20 W 34th St city: New York state: NY country: US postalCode: '10001' estimateDateTime: 2022-11-01T05:12:08.131Z currency: USD discountAmount: 0 subtotal: 100 exemptAmount: 0 taxableAmount: 91.85 taxAmount: 8.15 total: 100 lineItems: - number: 1 itemCode: cbWatch description: A winding watch. quantity: 1 amount: 100 isTaxInclusive: true isTaxable: true taxIdentifiers: - id: taxCode value: PT12312 discountAmount: 0 subtotal: 100 exemptAmount: 0 taxableAmount: 91.85 taxAmount: 8.15 total: 100 taxes: - number: 1 jurisdiction: code: '24354' type: STATE name: NEW YORK name: SELLER_USE rate: 4 taxableAmount: 91.85 taxAmount: 3.67 - number: 2 jurisdiction: code: '25353' type: CITY name: NEW YORK name: SELLER_USE rate: 4.5 taxableAmount: 91.85 taxAmount: 4.14 - number: 3 jurisdiction: code: '79774' type: OTHER name: METROPOLITAN COMMUTER TRANSPORTATION DISTRICT name: SELLER_USE rate: 0.375 taxableAmount: 91.85 taxAmount: 0.34 TaxEstimationRequestWithLineItemDiscount: description: >- A sample tax estimation request consisting of a line item with a corresponding discount. value: seller: address: line1: 412 63rd South Avenue city: Baltimore state: MD country: US postalCode: '21230' customer: name: John Doe customerCode: customer_test address: line1: '59, Starlight Avenue' city: Newark state: NJ country: US postalCode: '98712' estimateDateTime: 2022-11-01T05:12:08.131Z currency: USD lineItems: - number: 1 amount: 100 itemCode: cbWatch description: A winding watch. quantity: 1 discountAmount: 10 isTaxInclusive: false TaxEstimationResponseWithLineItemDiscount: description: >- A sample response to the tax estimation request consisting of a line item with a corresponding discount. value: seller: address: line1: 412 63rd South Avenue city: Baltimore state: MD country: US postalCode: '21230' hasNexus: true customer: name: John Doe customerCode: customer_test address: line1: '59, Starlight Avenue' city: Newark state: NJ country: US postalCode: '98712' estimateDateTime: 2022-11-01T05:12:08.131Z currency: USD discountAmount: 10 subtotal: 110 exemptAmount: 0 taxableAmount: 100 taxAmount: 5 total: 115 lineItems: - number: 1 itemCode: cbWatch description: A winding watch. quantity: 1 amount: 110 isTaxInclusive: false isTaxable: true exemptAmount: 0 discountAmount: 10 subtotal: 100 taxableAmount: 100 taxAmount: 5 total: 110 taxes: - number: 1 jurisdiction: code: '48' type: STATE name: CALIFORNIA name: SALE rate: 2.5 taxableAmount: 100 taxAmount: 2.5 - number: 2 jurisdiction: code: '27000' type: CITY name: SAN FRANCISCO name: SALE rate: 2.5 taxableAmount: 100 taxAmount: 2.5 TaxEstimationRequestWithCustomerExemption: description: >- A sample tax estimation request for a tax-exempt customer using an exemption code. value: seller: address: line1: 412 63rd South Avenue city: Baltimore state: MD country: US postalCode: '21230' customer: name: John Doe customerCode: customer_test address: line1: '59, Starlight Avenue' city: Newark state: NJ country: US postalCode: '98712' taxIdentifiers: - id: exemptionCode value: ex_gg1s2149812312 estimateDateTime: 2022-11-01T05:12:08.131Z currency: USD lineItems: - number: 1 itemCode: cbWatch description: A winding watch. quantity: 1 amount: 110 isTaxInclusive: false taxIdentifiers: - id: taxCode value: PT12312 TaxEstimationResponseWithCustomerExemption: description: >- A sample response to the tax estimation request for a tax-exempt customer using an exemption code. value: seller: address: line1: 412 63rd South Avenue city: Baltimore state: MD country: US postalCode: '21230' hasNexus: true customer: name: John Doe customerCode: customer_test address: line1: '59, Starlight Avenue' city: Newark state: NJ country: US postalCode: '98712' taxIdentifiers: - id: exemptionCode value: ex_gg1s2149812312 - id: category value: category1 estimateDateTime: 2022-11-01T05:12:08.131Z currency: USD discountAmount: 0 subtotal: 110 exemptAmount: 110 taxableAmount: 0 taxAmount: 0 total: 110 lineItems: - number: 1 itemCode: cbWatch description: A winding watch. quantity: 1 amount: 110 isTaxInclusive: false isTaxable: true taxIdentifiers: - id: taxCode value: PT12312 taxExemptType: CUSTOMER_EXEMPT taxExemptReason: The customer is exempt from taxes exemptAmount: 110 discountAmount: 0 subtotal: 110 taxableAmount: 0 taxAmount: 0 total: 0 taxes: - number: 1 jurisdiction: code: '48' type: STATE name: CALIFORNIA name: SALE rate: 5 taxableAmount: 0 taxAmount: 0 - number: 2 jurisdiction: code: '27000' type: CITY name: SAN FRANCISCO name: SALE rate: 10 taxableAmount: 0 taxAmount: 0 InvoiceRequestSimple: description: A request to create a simple invoice in the tax provider system. value: invoiceCode: inv_1234 documentDateTime: 2022-11-01T05:12:08.131Z currency: USD seller: address: line1: 412 63rd South Avenue city: Baltimore state: MD country: US postalCode: '21230' customer: name: John Doe customerCode: customer_test address: line1: '59, Starlight Avenue' city: Newark state: NJ country: US postalCode: '98712' subtotal: 100 exemptAmount: 0 discountAmount: 0 taxableAmount: 100 taxAmount: 15 total: 115 lineItems: - number: 1 itemCode: cbWatch description: A winding watch. quantity: 1 amount: 100 isTaxInclusive: false isTaxable: true taxIdentifiers: - id: taxCode value: PT12312 discountAmount: 0 subtotal: 100 exemptAmount: 0 taxableAmount: 100 taxAmount: 15 total: 115 taxes: - number: 1 jurisdiction: code: '48' type: STATE name: CALIFORNIA name: SALE rate: 5 taxableAmount: 100 taxAmount: 5 - number: 2 jurisdiction: code: '27000' type: CITY name: SAN FRANCISCO name: SALE rate: 10 taxableAmount: 100 taxAmount: 10 InvoiceResponseSimple: description: A simple invoice in the tax provider system. value: invoiceId: disney_001 invoiceCode: inv_1234 status: PENDING documentDateTime: 2022-11-01T05:12:08.131Z currency: USD seller: address: line1: 412 63rd South Avenue city: Baltimore state: MD country: US postalCode: '21230' hasNexus: true customer: name: John Doe customerCode: customer_test address: line1: '59, Starlight Avenue' city: Newark state: NJ country: US postalCode: '98712' subtotal: 100 discountAmount: 0 exemptAmount: 0 taxableAmount: 100 taxAmount: 15 total: 115 lineItems: - number: 1 itemCode: cbWatch description: A winding watch. quantity: 1 amount: 100 isTaxInclusive: false isTaxable: true taxIdentifiers: - id: taxCode value: PT12312 exemptAmount: 0 discountAmount: 0 subtotal: 100 taxableAmount: 100 taxAmount: 15 total: 115 taxes: - number: 1 jurisdiction: code: '48' type: STATE name: CALIFORNIA name: SALE rate: 5 taxableAmount: 100 taxAmount: 5 - number: 2 jurisdiction: code: '27000' type: CITY name: SAN FRANCISCO name: SALE rate: 10 taxableAmount: 100 taxAmount: 10 InvoiceRequestWithTaxInclusive: description: >- A request to create a simple invoice in the tax provider system with tax inclusive. value: invoiceCode: inv_1234 documentDateTime: 2022-11-01T05:12:08.131Z currency: USD seller: address: line1: 412 63rd South Avenue city: Baltimore state: MD country: US postalCode: '21230' customer: name: John Doe customerCode: customer_test address: line1: 20 W 34th St city: New York state: NY country: US postalCode: '10001' subtotal: 91.85 exemptAmount: 0 discountAmount: 0 taxableAmount: 91.85 taxAmount: 8.15 total: 100 lineItems: - number: 1 itemCode: cbWatch description: A winding watch. quantity: 1 amount: 100 isTaxInclusive: true isTaxable: true taxIdentifiers: - id: taxCode value: PT12312 discountAmount: 0 subtotal: 100 exemptAmount: 0 taxableAmount: 91.85 taxAmount: 8.15 total: 100 taxes: - number: 1 jurisdiction: code: '24354' type: STATE name: NEW YORK name: SELLER_USE rate: 4 taxableAmount: 91.85 taxAmount: 3.67 - number: 2 jurisdiction: code: '25353' type: CITY name: NEW YORK name: SELLER_USE rate: 4.5 taxableAmount: 91.85 taxAmount: 4.14 - number: 3 jurisdiction: code: '79774' type: OTHER name: METROPOLITAN COMMUTER TRANSPORTATION DISTRICT name: SELLER_USE rate: 0.375 taxableAmount: 91.85 taxAmount: 0.34 InvoiceResponseWithTaxInclusive: description: A simple invoice in the tax provider system with tax inclusive. value: invoiceId: disney_001 invoiceCode: inv_1234 status: PENDING documentDateTime: 2022-11-01T05:12:08.131Z currency: USD seller: address: line1: 412 63rd South Avenue city: Baltimore state: MD country: US postalCode: '21230' hasNexus: true customer: name: John Doe customerCode: customer_test address: line1: 20 W 34th St city: New York state: NY country: US postalCode: '10001' subtotal: 91.85 exemptAmount: 0 discountAmount: 0 taxableAmount: 91.85 taxAmount: 8.15 total: 100 lineItems: - number: 1 itemCode: cbWatch description: A winding watch. quantity: 1 amount: 100 isTaxInclusive: true isTaxable: true taxIdentifiers: - id: taxCode value: PT12312 discountAmount: 0 subtotal: 100 exemptAmount: 0 taxableAmount: 91.85 taxAmount: 8.15 total: 100 taxes: - number: 1 jurisdiction: code: '24354' type: STATE name: NEW YORK name: SELLER_USE rate: 4 taxableAmount: 91.85 taxAmount: 3.67 - number: 2 jurisdiction: code: '25353' type: CITY name: NEW YORK name: SELLER_USE rate: 4.5 taxableAmount: 91.85 taxAmount: 4.14 - number: 3 jurisdiction: code: '79774' type: OTHER name: METROPOLITAN COMMUTER TRANSPORTATION DISTRICT name: SELLER_USE rate: 0.375 taxableAmount: 91.85 taxAmount: 0.34 CreditNoteRequestFull: description: A request to send a credit note to the Tax Service Adapter. value: creditNoteCode: cn_2023_11_24_178 invoiceCode: inv_2023_11_30_78 invoiceId: disney_001 creditNoteType: FULL documentDateTime: 2022-11-01T05:12:08.131Z currency: USD seller: address: line1: 412 63rd South Avenue city: Baltimore state: MD country: US postalCode: '21230' customer: name: John Doe customerCode: customer_test address: line1: '59, Starlight Avenue' city: Newark state: NJ country: US postalCode: '98712' subtotal: 100 exemptAmount: 0 discountAmount: 0 taxableAmount: 100 taxAmount: 15 total: 115 CreditNoteResponseFull: description: >- The response from the Tax Service Adapter SPI containing the details of a credit note sent by Chargebee. value: creditNoteId: disney_002 creditNoteCode: cn_2023_11_24_178 invoiceCode: inv_2023_11_30_78 invoiceId: disney_001 status: PENDING creditNoteType: FULL documentDateTime: 2022-11-01T05:12:08.131Z currency: USD seller: address: line1: 412 63rd South Avenue city: Baltimore state: MD country: US postalCode: '21230' hasNexus: true customer: name: John Doe customerCode: customer_test address: line1: '59, Starlight Avenue' city: Newark state: NJ country: US postalCode: '98712' discountAmount: 0 subTotal: 100 exemptAmount: 0 taxableAmount: 100 taxAmount: 15 total: 115 lineItems: - number: 1 itemCode: cbWatch description: A winding watch. quantity: 1 amount: 100 isTaxInclusive: false isTaxable: true taxIdentifiers: - id: taxCode value: PT12312 exemptAmount: 0 discountAmount: 0 subtotal: 100 taxableAmount: 100 taxAmount: 15 total: 115 taxes: - number: 1 jurisdiction: code: '48' type: STATE name: CALIFORNIA name: SALE rate: 5 taxableAmount: 100 taxAmount: 5 - number: 2 jurisdiction: code: '27000' type: CITY name: SAN FRANCISCO name: SALE rate: 10 taxableAmount: 100 taxAmount: 10 CreditNoteRequestFullWithTaxInclusive: description: >- A request to send a credit note to the Tax Service Adapter with tax inclusive.. value: creditNoteCode: inv_1235 invoiceCode: disney_001 creditNoteType: FULL documentDateTime: 2022-11-01T05:12:08.131Z seller: address: line1: 412 63rd South Avenue city: Baltimore state: MD country: US postalCode: '21230' customer: name: John Doe customerCode: customer_test address: line1: 20 W 34th St city: New York state: NY country: US postalCode: '10001' currency: USD discountAmount: 0 subtotal: 100 exemptAmount: 0 taxableAmount: 91.85 taxAmount: 8.15 total: 100 lineItems: - number: 1 itemCode: cbWatch description: A winding watch. quantity: 1 amount: 100 isTaxInclusive: true isTaxable: true taxIdentifiers: - id: taxCode value: PT12312 discountAmount: 0 subtotal: 100 exemptAmount: 0 taxableAmount: 91.85 taxAmount: 8.15 total: 100 taxes: - number: 1 jurisdiction: code: '24354' type: STATE name: NEW YORK name: SELLER_USE rate: 4 taxableAmount: 91.85 taxAmount: 3.67 - number: 2 jurisdiction: code: '25353' type: CITY name: NEW YORK name: SELLER_USE rate: 4.5 taxableAmount: 91.85 taxAmount: 4.14 - number: 3 jurisdiction: code: '79774' type: OTHER name: METROPOLITAN COMMUTER TRANSPORTATION DISTRICT name: SELLER_USE rate: 0.375 taxableAmount: 91.85 taxAmount: 0.34 CreditNoteResponseFullWithTaxInclusive: description: >- The response from the Tax Service Adapter SPI containing the details of a credit note sent by Chargebee with tax inclusive.. value: creditNoteId: disney_002 creditNoteCode: disney_001 invoiceCode: inv_1235 status: PENDING creditNoteType: FULL documentDateTime: 2022-11-01T05:12:08.131Z seller: address: line1: 412 63rd South Avenue city: Baltimore state: MD country: US postalCode: '21230' hasNexus: true customer: name: John Doe customerCode: customer_test address: line1: 20 W 34th St city: New York state: NY country: US postalCode: '10001' currency: USD discountAmount: 0 subtotal: 100 exemptAmount: 0 taxableAmount: 91.85 taxAmount: 8.15 total: 100 lineItems: - number: 1 itemCode: cbWatch description: A winding watch. quantity: 1 amount: 100 isTaxInclusive: true isTaxable: true taxIdentifiers: - id: taxCode value: PT12312 discountAmount: 0 subtotal: 100 exemptAmount: 0 taxableAmount: 91.85 taxAmount: 8.15 total: 100 taxes: - number: 1 jurisdiction: code: '24354' type: STATE name: NEW YORK name: SELLER_USE rate: 4 taxableAmount: 91.85 taxAmount: 3.67 - number: 2 jurisdiction: code: '25353' type: CITY name: NEW YORK name: SELLER_USE rate: 4.5 taxableAmount: 91.85 taxAmount: 4.14 - number: 3 jurisdiction: code: '79774' type: OTHER name: METROPOLITAN COMMUTER TRANSPORTATION DISTRICT name: SELLER_USE rate: 0.375 taxableAmount: 91.85 taxAmount: 0.34 Error400ResponseInvalidCreditNoteId: description: Credit note id is invalid. summary: Invalid credit note id. value: errors: - code: INVALID_DATA message: Credit note id is not valid. entity: CreditNoteId entityField: creditNoteId Error400ResponseInvalidTaxCode: description: Item tax code is invalid. summary: Invalid item tax code. value: errors: - code: INVALID_DATA message: Invalid tax code is provided. entity: LineItem entityField: 'lineItem[0].productTaxCode' helpUrl: 'https://taxes.provider.com/tax-codes' Error400ResponseMissingCustomerAddress: description: Customer address is empty. summary: Missing customer address. value: errors: - code: MISSING_REQUIRED_DATA entity: Customer entityField: customer.address message: Customer address cannot be empty. Error500Response: description: Unexpected error during processing the request. summary: Unexpected error. value: message: Unexpected error during processing the request. AddressValidationValidRequest: description: Valid address request summary: Valid address request for full address verification value: address: line1: 1000 main line2: '' line3: '' city: Irvine state: CA country: US postalCode: '92615' AddressValidationInvalidRequest: description: Invalid address request summary: Invalid address request for full address verification value: address: line1: 1000 MAIN ST line2: '' line3: '' city: IRVINE state: CA country: US postalCode: '92614' AddressValidationValidResponse: description: >- Valid address verification response when address is validated successfully summary: Valid address verification response value: status: VALID AddressValidationInvalidResponse: description: The address provided for verification was Invalid summary: Invalid address verification response value: status: INVALID 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: ''