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.0
info:
version: 0.3.3
title: Taxes Service Adapter SPI
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
}
]
}
```
### Nexus Address
- Nexus Address list and configuration from the tax provider to use while calculating taxes
This is the format for passing the authorization key as HTTP header-based authorization.
`"Authorization":"{"<authorization_key>":"test_GykCvTykZFTBqHQAFzjMN9R1Thgdho0Q"}"`
servers:
- url: 'https://rest.taxes.provider.com/api/v1'
description: Production SPI server.
- url: 'https://sandbox.taxes.provider.com/api/v1'
description: Sandbox SPI server.
tags:
- name: Address
description: "Endpoints to validate an address and check its taxability."
- name: TaxEstimate
description: "Endpoints to estimate taxes."
- name: Invoice
description: "Endpoints to manage invoices sent to the Tax Service Provider."
- name: CreditNote
description: "Endpoints to manage credit notes sent to the Tax Service Provider."
- name: Authentication
description: "Endpoints to validate the credentials used for calling the Tax Service Adapter."
- name: Health
description: "Endpoints to monitor the health of the Tax Service Provider and the Tax Service Adapter."
- name: Nexus
description: Nexus Address lists API Documentation
paths:
/tax-estimate:
post:
tags:
- TaxEstimate
summary: Estimate tax
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:
schema:
$ref: '#/components/schemas/TaxEstimationRequest'
examples:
TaxEstimationRequestSimple:
$ref: '#/components/examples/TaxEstimationRequestSimple'
TaxEstimationRequestWithLineItemDiscount:
$ref: '#/components/examples/TaxEstimationRequestWithLineItemDiscount'
TaxEstimationRequestWithCustomerExemption:
$ref: '#/components/examples/TaxEstimationRequestWithCustomerExemption'
responses:
'200':
description: "Tax estimated successfully for given line items."
content:
application/json:
schema:
$ref: '#/components/schemas/TaxEstimationResponse'
examples:
TaxEstimationResponseSimple:
$ref: '#/components/examples/TaxEstimationResponseSimple'
TaxEstimationResponseWithLineItemDiscount:
$ref: '#/components/examples/TaxEstimationResponseWithLineItemDiscount'
TaxEstimationResponseWithCustomerExemption:
$ref: '#/components/examples/TaxEstimationResponseWithCustomerExemption'
'400':
$ref: '#/components/responses/Error400TaxEstimate'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'404':
$ref: '#/components/responses/Error404'
'429':
$ref: '#/components/responses/Error429'
'500':
$ref: '#/components/responses/Error500'
'503':
$ref: '#/components/responses/Error503'
/invoices:
post:
tags:
- Invoice
summary: Create Invoice
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:
schema:
$ref: '#/components/schemas/InvoiceRequest'
examples:
InvoiceRequestSimple:
$ref: '#/components/examples/InvoiceRequestSimple'
responses:
'201':
description: "Invoice created successfully."
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
examples:
InvoiceResponseSimple:
$ref: '#/components/examples/InvoiceResponseSimple'
'400':
$ref: '#/components/responses/Error400Invoice'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'429':
$ref: '#/components/responses/Error429'
'500':
$ref: '#/components/responses/Error500'
'503':
$ref: '#/components/responses/Error503'
/invoices/{invoiceId}:
get:
tags:
- Invoice
summary: "Retrieve Invoice"
description: "This endpoint is used to retrieve an invoice for a given invoice id."
operationId: fetchInvoice
parameters:
- $ref: '#/components/parameters/InvoiceIdPathParam'
responses:
'200':
description: "Invoice retrieved successfully."
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'404':
$ref: '#/components/responses/Error404'
'429':
$ref: '#/components/responses/Error429'
'500':
$ref: '#/components/responses/Error500'
'503':
$ref: '#/components/responses/Error503'
/invoices/{invoiceId}/commit:
post:
tags:
- Invoice
summary: "Commit Invoice"
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:
- $ref: '#/components/parameters/InvoiceIdPathParam'
responses:
'204':
description: "Invoice committed successfully."
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'404':
$ref: '#/components/responses/Error404'
'429':
$ref: '#/components/responses/Error429'
'500':
$ref: '#/components/responses/Error500'
'503':
$ref: '#/components/responses/Error503'
/invoices/{invoiceId}/void:
post:
tags:
- Invoice
summary: "Void Invoice"
description: "This endpoint is used to mark a specific invoice as void. Voiding cancels the invoice without deleting it."
operationId: voidInvoice
parameters:
- $ref: '#/components/parameters/InvoiceIdPathParam'
responses:
'204':
description: Invoice voided successfully.
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'404':
$ref: '#/components/responses/Error404'
'429':
$ref: '#/components/responses/Error429'
'500':
$ref: '#/components/responses/Error500'
'503':
$ref: '#/components/responses/Error503'
/credit-notes:
post:
tags:
- CreditNote
summary: "Create credit note"
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:
schema:
$ref: '#/components/schemas/CreditNoteRequest'
examples:
CreditNoteRequestFull:
$ref: '#/components/examples/CreditNoteRequestFull'
responses:
'201':
description: "Credit note created successfully."
content:
application/json:
schema:
$ref: '#/components/schemas/CreditNote'
examples:
CreditNoteResponseFull:
$ref: '#/components/examples/CreditNoteResponseFull'
'400':
$ref: '#/components/responses/Error400CreditNote'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'429':
$ref: '#/components/responses/Error429'
'500':
$ref: '#/components/responses/Error500'
'503':
$ref: '#/components/responses/Error503'
/credit-notes/{creditNoteId}:
get:
tags:
- CreditNote
summary: "Retrieve credit note"
description: "This endpoint is used to retrieve a specific credit note using the unique credit note id."
operationId: fetchCreditNote
parameters:
- $ref: '#/components/parameters/CreditNoteIdPathParam'
responses:
'200':
description: "Credit note retrieved successfully."
content:
application/json:
schema:
$ref: '#/components/schemas/CreditNote'
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'404':
$ref: '#/components/responses/Error404'
'429':
$ref: '#/components/responses/Error429'
'500':
$ref: '#/components/responses/Error500'
'503':
$ref: '#/components/responses/Error503'
/credit-notes/{creditNoteId}/commit:
post:
tags:
- CreditNote
summary: "Commit credit note"
description: "This endpoint is used to mark a credit note as committed. Once committed, the credit note is considered as finalized."
operationId: commitCreditNote
parameters:
- $ref: '#/components/parameters/CreditNoteIdPathParam'
responses:
'204':
description: Credit note committed successfully.
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'404':
$ref: '#/components/responses/Error404'
'429':
$ref: '#/components/responses/Error429'
'500':
$ref: '#/components/responses/Error500'
'503':
$ref: '#/components/responses/Error503'
/credit-notes/{creditNoteId}/void:
post:
tags:
- CreditNote
summary: "Void credit note"
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:
- $ref: '#/components/parameters/CreditNoteIdPathParam'
responses:
'204':
description: "Credit note voided successfully."
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'404':
$ref: '#/components/responses/Error404'
'429':
$ref: '#/components/responses/Error429'
'500':
$ref: '#/components/responses/Error500'
'503':
$ref: '#/components/responses/Error503'
/credentials/validate:
post:
summary: "Validate credentials"
description: "This endpoint is used to validate the credentials used to call the Tax Service Adapter SPI."
operationId: validateCredentials
tags:
- Authentication
responses:
'200':
description: Authentication succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/CredentialValidationResponse'
example:
status: VALID
'401':
description: Authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/CredentialValidationResponse'
example:
status: INVALID
'429':
$ref: '#/components/responses/Error429'
'500':
$ref: '#/components/responses/Error500'
'503':
$ref: '#/components/responses/Error503'
/health:
get:
summary: "Fetch the health status of the Tax Service Provider."
description: "This endpoint is used to fetch the health status of the Tax Service Provider."
operationId: fetchHealth
tags:
- Health
# NOTE: No security scheme for the health endpoint.
security:
- {}
responses:
'200':
description: Service is healthy.
content:
application/json:
schema:
$ref: '#/components/schemas/HealthCheckResponse'
example:
status: UP
version: 1.0.0
description: The service is healthy.
components:
- id: app-db1-memory
name: Application Database
type: DATABASE
status: UP
- id: tax-cb-adapter-server
name: Tax Adapter API Server
type: ADAPTER
status: UP
- id: tax-rest-server
name: Tax API Server
type: API
status: UP
time: '2022-11-01T10:42:08.131+05:30'
'429':
$ref: '#/components/responses/Error429'
'500':
$ref: '#/components/responses/Error500'
'503':
$ref: '#/components/responses/Error503'
/address/validate:
post:
summary: "Address validation"
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
tags:
- Address
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AddressValidationRequest'
examples:
AddressValidationValidRequest:
$ref: '#/components/examples/AddressValidationValidRequest'
AddressValidationInvalidRequest:
$ref: '#/components/examples/AddressValidationInvalidRequest'
responses:
'200':
description: "Address is validated successfully"
content:
application/json:
schema:
$ref: '#/components/schemas/AddressValidationResponse'
examples:
AddressValidationValidResponse:
$ref: '#/components/examples/AddressValidationValidResponse'
AddressValidationInvalidResponse:
$ref: '#/components/examples/AddressValidationInvalidResponse'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
example:
errors:
- code: INVALID_DATA
message: Empty address provided.
entity: Address
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'429':
$ref: '#/components/responses/Error429'
'500':
$ref: '#/components/responses/Error500'
'503':
$ref: '#/components/responses/Error503'
/address/check-taxability:
post:
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
tags:
- Address
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CheckAddressTaxabilityRequest'
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'
responses:
'200':
description: "Tax can be calculated for the address provided."
content:
application/json:
schema:
$ref: '#/components/schemas/CheckAddressTaxabilityResponse'
examples:
CheckAddressTaxabilityValidResponse-Option1:
$ref: '#/components/examples/CheckAddressTaxabilityValidResponse-Option1'
CheckAddressTaxabilityInalidResponse-Option1:
$ref: '#/components/examples/CheckAddressTaxabilityInalidResponse-Option1'
CheckAddressTaxabilityValidResponse-Option2:
$ref: '#/components/examples/CheckAddressTaxabilityValidResponse-Option2'
CheckAddressTaxabilityInalidResponse-Option2:
$ref: '#/components/examples/CheckAddressTaxabilityInalidResponse-Option2'
CheckAddressTaxabilityValidResponse-Option3:
$ref: '#/components/examples/CheckAddressTaxabilityValidResponse-Option3'
CheckAddressTaxabilityInalidResponse-Option3:
$ref: '#/components/examples/CheckAddressTaxabilityInalidResponse-Option3'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
example:
errors:
- code: INVALID_DATA
message: Empty address provided.
entity: Address
'401':
$ref: '#/components/responses/Error401'
'403':
$ref: '#/components/responses/Error403'
'429':
$ref: '#/components/responses/Error429'
'500':
$ref: '#/components/responses/Error500'
'503':
$ref: '#/components/responses/Error503'
/nexus/{merchantId}:
get:
summary: Fetch nexus Addresses configured by tax provider
description: Fetch nexus Addresses configured by tax provider
operationId: fetchNexusAddress
tags:
- Nexus
parameters:
- $ref: '#/components/parameters/MerchantIdPathParam'
responses:
'200':
description: Nexus address list fetched successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/NexusAddressList'
examples:
SimpleNexusList:
$ref: '#/components/examples/FetchNexusAddressListResponseSimple'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/NexusErrorResponse'
examples:
Error400MissingMerchantId:
$ref: '#/components/examples/Error400ResponseMissingMerchantId'
'401':
$ref: '#/components/responses/Error401Nexus'
'403':
$ref: '#/components/responses/Error403Nexus'
'404':
$ref: '#/components/responses/Error404Nexus'
'500':
$ref: '#/components/responses/Error500Nexus'
'503':
$ref: '#/components/responses/Error503Nexus'
components:
schemas:
TaxEstimationRequest:
type: object
required:
- seller
- customer
- estimateDateTime
- currency
- lineItems
additionalProperties: false
description: "Defines the parameters of a tax estimation request. This is sent to the Tax Service Adapter by Chargebee to estimate taxes for one or more line items."
properties:
seller:
$ref: '#/components/schemas/Seller'
customer:
$ref: '#/components/schemas/Customer'
estimateDateTime:
type: string
description: "The time as of which the tax estimation is to be calculated. This can be a value in the past. For example, if the value is provided as 2022-10-28T15:36:28.129+05:30, then the tax rates applicable on October 28, 2022, at 15:36:28.129, with an offset of +05:30 ahead of UTC/GMT are used for calculations. In case of a merchant site located in UTC, these datatypes would send a timestamp in the format 2022-11-11T15:40:44.65Z. This timestamp represents November 11, 2022, at 15:40:44.65, with the 'Z' indicating that the time is in UTC."
format: date-time
currency:
$ref: '#/components/schemas/Currency'
lineItems:
type: array
description: "Contains the details of each line item in the tax estimation request."
items:
$ref: '#/components/schemas/TaxEstimationLineItemRequest'
minItems: 1
maxItems: 1250
TaxEstimationLineItemRequest:
type: object
description: "Represents the details of a line item in a tax estimation request."
required:
- number
- amount
- isTaxInclusive
additionalProperties: false
properties:
number:
type: integer
description: "Index or serial number of the line item."
minimum: 1
itemCode:
type: string
description: "The unique identifier (in Chargebee) of the product corresponding to the line item. If the line item corresponds to a one-off charge, then this identifier is not provided."
maxLength: 50
description:
type: string
description: "The description of the line item."
maxLength: 250
quantity:
type: number
format: double
minimum: 0
description: "The quantity associated with this line item."
unitPrice:
type: number
format: double
minimum: 0
description: "The unit price for this line item. In case of [tiered pricing](https://www.chargebee.com/docs/1.0/plans.html#tiered-pricing) where the unit price varies for each quantity tier, this is the average unit price."
amount:
type: number
description: "The amount for this line item. This is `unitPrice` × `quantity`."
format: double
discountAmount:
type: number
description: "The discount applied to this line item."
format: double
isTaxInclusive:
type: boolean
description: "Indicates whether (`amount` - `discountAmount`) is inclusive of taxes."
taxCodeFields:
type: array
description: The tax code fields of the product used for tax calculation.
items:
$ref: '#/components/schemas/FieldItem'
maxItems: 10
TaxEstimationResponse:
description: "The response sent by the Tax Service Adapter to Chargebee for a tax estimation request."
type: object
required:
- seller
- customer
- estimateDateTime
- currency
- subtotal
- exemptAmount
- discountAmount
- taxableAmount
- taxAmount
- total
- lineItems
additionalProperties: false
properties:
seller:
$ref: '#/components/schemas/Seller'
customer:
$ref: '#/components/schemas/Customer'
estimateDateTime:
type: string
description: "The time as of which the tax estimation is to be calculated. This can be a value in the past. For example, if the value is provided as 2022-10-28T15:36:28.129+05:30, then the tax rates applicable on October 28, 2022, at 15:36:28.129, with an offset of +05:30 ahead of UTC/GMT are used for calculations. In case of a merchant site located in UTC, these datatypes would send a timestamp in the format 2022-11-11T15:40:44.65Z. This timestamp represents November 11, 2022, at 15:40:44.65, with the 'Z' indicating that the time is in UTC."
format: date-time
currency:
$ref: '#/components/schemas/Currency'
subtotal:
type: number
description: "The amount after discounts. This is the sum of all `lineItems.subtotal`."
format: double
exemptAmount:
type: number
description: "The part of the `subtotal` that is exempted from tax."
format: double
discountAmount:
type: number
description: "The total discount applied. This is the sum of all `lineItems.discount`."
format: double
taxableAmount:
type: number
description: "The part of the `subtotal` that is taxable."
format: double
taxAmount:
type: number
description: "The total tax payable. This is the sum of all `lineItems.taxAmount`."
format: double
total:
type: number
description: "The total after discounts and taxes. This is the same as `subtotal` if it is tax inclusive; otherwise it is `subtotal` + `taxAmount`. `total` can also be expressed as `exemptAmount` + `taxableAmount` + `taxAmount`."
format: double
lineItems:
type: array
description: "List of line item details for the tax estimation response."
items:
$ref: '#/components/schemas/InvoiceLineItem'
minItems: 1
maxItems: 1250
InvoiceLineItem:
type: object
required:
- number
- amount
- subtotal
- isTaxInclusive
- isTaxable
- exemptAmount
- discountAmount
- taxableAmount
- taxAmount
- total
- taxes
additionalProperties: false
description: "The details of a line item."
properties:
number:
type: integer
description: "Index or serial number of the line item."
minimum: 1
itemCode:
type: string
description: "The unique identifier (in Chargebee) of the product corresponding to the line item. If the line item corresponds to a one-off charge, then this identifier is not present."
maxLength: 50
description:
type: string
description: "The description of the line item."
maxLength: 250
quantity:
type: number
description: "The quantity associated with this line item."
format: double
minimum: 0
unitPrice:
type: number
format: double
minimum: 0
description: "The unit price for this line item. In case of [tiered pricing](https://www.chargebee.com/docs/1.0/plans.html#tiered-pricing) where the unit price varies for each quantity tier, this is the average unit price."
amount:
type: number
description: "The amount for this line item. This is `unitPrice` × `quantity`."
format: double
subtotal:
type: number
description: "The amount after discounts for this line item. This is `amount` - `discountAmount`."
format: double
isTaxInclusive:
type: boolean
description: "Indicates whether the `subtotal` for this line item is inclusive of taxes."
isTaxable:
type: boolean
description: "Indicates whether this line item is taxable."
taxCodeFields:
type: array
description: The tax code fields of the product used for tax calculation.
items:
$ref: '#/components/schemas/FieldItem'
maxItems: 10
taxExemptType:
$ref: '#/components/schemas/TaxExemptType'
taxExemptReason:
$ref: '#/components/schemas/TaxExemptReason'
exemptAmount:
type: number
description: "The part of this line item's `subtotal` that is exempted from tax."
format: double
discountAmount:
type: number
description: "The discount applied to this line item."
format: double
taxableAmount:
type: number
description: "The part of this line item's `subtotal` that is taxable."
format: double
taxAmount:
type: number
description: "The tax payable for this line item. This is the sum of all `taxes.taxAmount` for this line item."
format: double
total:
type: number
description: "The total for this line item after discounts and taxes. This is the same as `subtotal` if it is tax inclusive; otherwise it is `subtotal` + `taxAmount`. `total` can also be expressed as `exemptAmount` + `taxableAmount` + `taxAmount`."
format: double
isPartialTax:
type: boolean
description: "Indicates if taxes were applied only partially for this line item."
taxes:
type: array
description: "List of taxes applied for this line item under each jurisdiction."
items:
$ref: '#/components/schemas/TaxLineItem'
minItems: 0
maxItems: 10
FieldItem:
type: object
required:
- id
- value
properties:
id:
type: string
description: The id of the field.
maxLength: 50
value:
type: string
description: The value of the field.
maxLength: 50
TaxLineItem:
type: object
description: "The details of tax applied under a specific jurisdiction."
required:
- number
- jurisdiction
- name
- rate
- taxableAmount
- taxAmount
additionalProperties: false
properties:
number:
type: integer
description: "Index or serial number of this tax line item."
minimum: 1
jurisdiction:
$ref: '#/components/schemas/TaxJurisdiction'
name:
type: string
description: "The name of the tax applied."
example: GST
rate:
$ref: '#/components/schemas/TaxRate'
taxableAmount:
type: number
description: "The part of the line item's `subtotal` that is taxable under this jurisdiction."
format: double
taxAmount:
type: number
description: "The tax payable for the line item under this jurisdiction."
format: double
InvoiceRequest:
type: object
required:
- invoiceCode
- documentDateTime
- currency
- seller
- customer
- subtotal
- exemptAmount
- discountAmount
- taxableAmount
- taxAmount
- total
- lineItems
additionalProperties: false
description: "The details of an invoice sent to the Tax Service Adapter by Chargebee."
properties:
invoiceCode:
type: string
description: "The unique identifier of the invoice in Chargebee."
maxLength: 50
documentDateTime:
type: string
description: "The date and time at which the invoice was generated in Chargebee. For example, if the value is 2022-10-28T15:36:28.129+05:30, then the timestamp represents October 28, 2022, at 15:36:28.129, with an offset of +05:30. This means that the time represented is 5 hours and 30 minutes ahead of UTC/GMT.In the case of a merchant site located in UTC, these datatypes would send a timestamp in the format 2022-11-11T15:40:44.65Z. This timestamp represents November 11, 2022, at 15:40:44.65, with the 'Z' indicating that the time is in UTC."
format: date-time
currency:
$ref: '#/components/schemas/Currency'
seller:
$ref: '#/components/schemas/Seller'
customer:
$ref: '#/components/schemas/Customer'
subtotal:
type: number
description: "The amount after discounts. This is the sum of all `lineItems.subtotal`."
format: double
exemptAmount:
type: number
description: "The part of the `subtotal` that is exempted from tax."
format: double
discountAmount:
type: number
description: "The total discount applied. This is the sum of all `lineItems.discount`."
format: double
taxableAmount:
type: number
description: "The part of the `subtotal` that is taxable."
format: double
taxAmount:
type: number
description: "The total tax payable. This is the sum of all `lineItems.taxAmount`."
format: double
total:
type: number
description: "The total after discounts and taxes. This is the same as `subtotal` if it is tax inclusive; otherwise it is `subtotal` + `taxAmount`. `total` can also be expressed as `exemptAmount` + `taxableAmount` + `taxAmount`."
format: double
lineItems:
type: array
items:
$ref: '#/components/schemas/InvoiceLineItem'
minItems: 1
maxItems: 1250
Invoice:
type: object
description: "The details of an invoice as returned by the Tax Service Adapter."
required:
- invoiceId
- invoiceCode
- documentDateTime
- status
- currency
- seller
- customer
- discountAmount
- subtotal
- exemptAmount
- taxableAmount
- taxAmount
- total
- lineItems
additionalProperties: false
properties:
invoiceId:
type: string
description: "The unique identifier of the invoice in the Tax Service Adapter or the Tax Service Provider."
maxLength: 50
invoiceCode:
type: string
description: "The unique identifier of the invoice in Chargebee."
maxLength: 50
documentDateTime:
type: string
description: "The date and time at which the invoice was generated in Chargebee. For example, if the value is 2022-10-28T15:36:28.129+05:30, then the timestamp represents October 28, 2022, at 15:36:28.129, with an offset of +05:30. This means that the time represented is 5 hours and 30 minutes ahead of UTC/GMT.In the case of a merchant site located in UTC, these datatypes would send a timestamp in the format 2022-11-11T15:40:44.65Z. This timestamp represents November 11, 2022, at 15:40:44.65, with the 'Z' indicating that the time is in UTC."
format: date-time
status:
$ref: '#/components/schemas/DocumentStatus'
currency:
$ref: '#/components/schemas/Currency'
seller:
$ref: '#/components/schemas/Seller'
customer:
$ref: '#/components/schemas/Customer'
subtotal:
type: number
description: "The amount after discounts. This is the sum of all `lineItems.subtotal`."
format: double
exemptAmount:
type: number
description: "The part of the `subtotal` that is exempted from tax."
format: double
discountAmount:
type: number
description: "The total discount applied. This is the sum of all `lineItems.discount`."
format: double
taxableAmount:
type: number
description: "The part of the `subtotal` that is taxable."
format: double
taxAmount:
type: number
description: "The total tax payable. This is the sum of all `lineItems.taxAmount`."
format: double
total:
type: number
description: "The total after discounts and taxes. This is the same as `subtotal` if it is tax inclusive; otherwise it is `subtotal` + `taxAmount`. `total` can also be expressed as `exemptAmount` + `taxableAmount` + `taxAmount`."
format: double
lineItems:
type: array
items:
$ref: '#/components/schemas/InvoiceLineItem'
minItems: 1
maxItems: 1250
CreditNoteRequest:
type: object
description: "The details of a credit note sent to the Tax Service Adapter by Chargebee. 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."
required:
- creditNoteCode
- invoiceCode
- creditNoteType
- documentDateTime
- currency
- seller
- customer
- total
- exemptAmount
- discountAmount
- taxableAmount
- taxAmount
## NOTE: lineItems not in required fields as it's not necessary for full credit note requests.
additionalProperties: false
properties:
creditNoteCode:
type: string
description: "The unique identifier of the credit note in Chargebee."
maxLength: 50
invoiceCode:
type: string
description: "The unique identifier of the invoice in Chargebee to which this credit note belongs."
maxLength: 50
creditNoteType:
$ref: '#/components/schemas/CreditNoteType'
documentDateTime:
type: string
description: "The date and time at which the credit note was created in Chargebee. For example, if the value is 2022-10-28T15:36:28.129+05:30, then the timestamp represents October 28, 2022, at 15:36:28.129, with an offset of +05:30. This means that the time represented is 5 hours and 30 minutes ahead of UTC/GMT. In the case of a merchant site located in UTC, these datatypes would send a timestamp in the format 2022-11-11T15:40:44.65Z. This timestamp represents November 11, 2022, at 15:40:44.65, with the 'Z' indicating that the time is in UTC."
format: date-time
currency:
$ref: '#/components/schemas/Currency'
seller:
$ref: '#/components/schemas/Seller'
customer:
$ref: '#/components/schemas/Customer'
total:
type: number
description: "The total amount of the credit note. `total` can be expressed as `exemptAmount` + `taxableAmount` + `taxAmount`."
format: double
exemptAmount:
type: number
description: "The amount exempted from tax."
format: double
discountAmount:
type: number
description: "The total discount applied. This is the sum of all `lineItems.discount`."
format: double
taxableAmount:
type: number
description: "The amount upon which the tax is calculated."
format: double
taxAmount:
type: number
description: "The total tax payable. This is the sum of all `lineItems.taxAmount`."
format: double
roundingAmount:
type: number
description: The rounding amount added to the total amount to account for fractional correction.
format: double
lineItems:
type: array
items:
$ref: '#/components/schemas/InvoiceLineItem'
minItems: 1
maxItems: 1250
CreditNote:
type: object
description: "The details of a credit note returned by 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."
required:
- creditNoteId
- creditNoteCode
- invoiceCode
- creditNoteType
- documentDateTime
- status
- currency
- seller
- customer
- discountAmount
- subTotal
- exemptAmount
- taxableAmount
- taxAmount
- total
- lineItems
additionalProperties: false
properties:
creditNoteId:
type: string
description: "The unique identifier of the credit note at the Tax Service Provider or Tax Service Adapter."
maxLength: 50
creditNoteCode:
type: string
description: "The unique identifier of the credit note in Chargebee."
maxLength: 50
invoiceCode:
type: string
description: "The unique identifier of the invoice in Chargebee to which this credit note belongs."
maxLength: 50
creditNoteType:
$ref: '#/components/schemas/CreditNoteType'
documentDateTime:
type: string
description: "The date and time at which the credit note was created in Chargebee. For example, if the value is 2022-10-28T15:36:28.129+05:30, then the timestamp represents October 28, 2022, at 15:36:28.129, with an offset of +05:30. This means that the time represented is 5 hours and 30 minutes ahead of UTC/GMT. In the case of a merchant site located in UTC, these datatypes would send a timestamp in the format 2022-11-11T15:40:44.65Z. This timestamp represents November 11, 2022, at 15:40:44.65, with the 'Z' indicating that the time is in UTC."
format: date-time
status:
$ref: '#/components/schemas/DocumentStatus'
currency:
$ref: '#/components/schemas/Currency'
seller:
$ref: '#/components/schemas/Seller'
customer:
$ref: '#/components/schemas/Customer'
discountAmount:
type: number
description: "The total discount applied. This is the sum of all `lineItems.discount`."
format: double
subtotal:
type: number
description: "The amount after discounts. This is the sum of all `lineItems.subtotal`."
format: double
exemptAmount:
type: number
description: "The amount exempted from tax."
format: double
taxableAmount:
type: number
description: "The amount upon which the tax is calculated."
format: double
taxAmount:
type: number
description: "The total tax payable. This is the sum of all `lineItems.taxAmount`."
format: double
total:
type: number
description: "The total amount of the credit note. `total` can be expressed as `exemptAmount` + `taxableAmount` + `taxAmount`."
format: double
roundingAmount:
type: number
description: The rounding amount added to the total amount to account for fractional correction.
format: double
lineItems:
type: array
items:
$ref: '#/components/schemas/InvoiceLineItem'
minItems: 1
maxItems: 1250
Seller:
type: object
description: The details of the seller involved in the transaction including company code and address.
required:
- address
additionalProperties: false
properties:
taxRegistrationNumber:
$ref: '#/components/schemas/TaxRegistrationNumber'
address:
$ref: '#/components/schemas/Address'
hasNexus:
type: boolean
description: "Determines whether a tax nexus exists between the Seller and the tax authority at the address provided."
Customer:
type: object
description: "The details of the Customer."
required:
- customerCode
- address
additionalProperties: false
properties:
customerCode:
type: string
description: "The unique identifier for the Customer in Chargebee."
maxLength: 50
address:
$ref: '#/components/schemas/Address'
taxRegistrationNumber:
$ref: '#/components/schemas/TaxRegistrationNumber'
exemptionFields:
type: array
description: "The exemption fields of the customer used for tax exemption."
items:
$ref: '#/components/schemas/FieldItem'
maxItems: 10
hasNexus:
type: boolean
description: "Determines whether a tax nexus exists between the Seller and the tax authority at the address provided."
CreditNoteType:
type: string
description: "Whether the credit note was created for the full amount on the invoice or only for a part of the invoice amount."
enum:
- FULL
- PARTIAL
DocumentStatus:
type: string
description: Status of the invoice document.
enum:
- PENDING
- COMMITTED
- VOIDED
## NOTE: Removed DELETED because it's not going to be shown in a response. 404 will be thrown for deleted documents.
TaxRegistrationNumber:
type: string
description: "The tax registration number of a business in a country. For example, this is the GSTIN for India or the VAT number for EU or Australia."
maxLength: 30
TaxExemptType:
type: string
description: "The tax exemption type for a line item. This is a mandatory parameter while applying tax exemption on any line-item."
enum:
- PRODUCT_EXEMPT
- CUSTOMER_EXEMPT
- REGION_EXEMPT
- REVERSE_CHARGE
- ZERO_RATE_TAX
- HIGH_VALUE_PHYSICAL_GOODS
- EXPORT
- ZERO_VALUE_ITEM
TaxExemptReason:
type: string
description: "The reason due to which a line item is exempted from tax. This is a mandatory parameter while applying tax exemption on any line-item."
maxLength: 250
example: "The customer is exempt from taxes."
TaxJurisdiction:
type: object
description: "The tax jurisdiction details."
required:
- code
- type
- name
additionalProperties: false
properties:
code:
type: string
description: "The jurisdiction code."
maxLength: 50
type:
$ref: '#/components/schemas/TaxJurisdictionType'
name:
type: string
description: "The jurisdiction name."
maxLength: 50
TaxJurisdictionType:
type: string
description: "The type of tax jurisdiction."
enum:
- COUNTRY
- FEDERAL
- STATE
- COUNTY
- CITY
- SPECIAL
- OTHER
Currency:
type: string
description: "The [currency](https://en.wikipedia.org/wiki/Currency) in the [ISO-4217 format](https://www.iso.org/iso-4217-currency-codes.html)."
minLength: 3
maxLength: 3
TaxRate:
description: "The tax rate expressed in percentage."
type: number
format: double
maximum: 100
CredentialValidationResponse:
type: object
required:
- status
properties:
status:
$ref: '#/components/schemas/CredentialStatus'
CredentialStatus:
type: string
description: "The status of the credentials used for authentication."
enum:
- VALID
- INVALID
HealthCheckResponse:
type: object
required:
- status
- components
- time
properties:
version:
type: string
minLength: 1
description:
type: string
description: "The description of the health status returned by the Tax Service Adapter."
maxLength: 250
status:
$ref: '#/components/schemas/HealthStatus'
components:
type: array
description: "List of health status details for each component reported by the Tax Service Adapter."
items:
$ref: '#/components/schemas/HealthCheckComponent'
time:
type: string
description: "The timestamp of the health status reported by the Tax Service Adapter."
format: date-time
HealthCheckComponent:
type: object
description: "The health status details of a specific component reported by the Tax Service Adapter."
required:
- id
- name
- type
- status
properties:
id:
type: string
description: "The id of the component."
maxLength: 50
name:
type: string
description: "The name of the component."
maxLength: 150
type:
type: string
description: |
The type of component affected when `status` is `WARN` or `DOWN`. The possible values are:
- `ADAPTER`: The reported status is for the Tax Service Adapter.
- `API`: The reported status is for the Tax Service Provider.
- `DATABASE`: The reported status is for a database dependency of the Tax 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
description:
type: string
description: "The detailed status of the component."
maxLength: 250
status:
$ref: '#/components/schemas/HealthStatus'
endpoints:
type: array
description: "When the `status` of the component is not `UP`, then the list of endpoints affected."
items:
type: string
HealthStatus:
type: string
description: "The status of a specific component reported by the Tax Service Adapter."
enum:
- UP
- DOWN
- WARN
AddressValidationRequest:
type: object
description: |-
The verification request containing the address. The following fields are mandatory -
- line1
- city
- postalCode
- state
- country
additionalProperties: false
properties:
address:
$ref: '#/components/schemas/Address'
CheckAddressTaxabilityRequest:
type: object
description: The taxability request containing the address. Postal code & Country is mandatory.
additionalProperties: false
properties:
address:
$ref: '#/components/schemas/Address'
AddressValidationResponse:
type: object
required:
- status
properties:
status:
$ref: '#/components/schemas/AddressValidationStatus'
CheckAddressTaxabilityResponse:
type: object
required:
- isTaxable
properties:
isTaxable:
type: boolean
description: The taxability of the address.
AddressValidationStatus:
type: string
description: The valdidation status of an address.
enum:
- VALID
- INVALID
Address:
type: object
description: Represents the address used for validation.
properties:
line1:
type: string
description: First line of the street address
maxLength: 180
line2:
type: string
description: Second line of the street address
maxLength: 150
line3:
type: string
description: Third line of the street address
maxLength: 150
city:
type: string
description: The city of the address
maxLength: 50
state:
type: string
description: The state of the address following the ISO 3166-2 state/province code without the country prefix.
maxLength: 50
postalCode:
type: string
description: Postal Code / Zip Code of the address.
maxLength: 20
country:
type: string
description: The country of the address following the ISO 3166-1 alpha-2 standard.
maxLength: 2
BasicErrorResponse:
type: object
description: The basic error response containing the error message and the help documentation link.
required:
- message
additionalProperties: false
properties:
message:
type: string
description: The description of the error with details about it's cause.
maxLength: 250
example: Invalid Credentials
helpUrl:
type: string
description: The link to the documentation for more information about the error and the corrective action.
format: uri
example: 'https://apidocs.chargebee.com#Authentication'
ValidationErrorResponse:
type: object
description: The error response for validation errors with the respective entity and its field information.
required:
- errors
properties:
errors:
type: array
items:
type: object
required:
- code
- message
properties:
entity:
type: string
description: The target entity that has the invalid field or value.
maxLength: 20
example: customer
entityField:
type: string
description: The field of an entity that has the invalid value.
maxLength: 250
example: lineItems[0].taxCodeFields[0].value
code:
$ref: '#/components/schemas/ErrorCode'
message:
type: string
description: A short message describing the reason for the error.
maxLength: 250
example: Invalid tax code provided.
helpUrl:
type: string
description: The link to the documentation for more information about the error and the corrective action.
format: uri
example: 'https://apidocs.chargebee.com#Authentication'
ErrorCode:
type: string
description: The error codes classify the type of exception that occured 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
NexusAddressList:
type: array
description: The NexusAddressList contains all the Addresses supported by tax provider
items:
$ref: '#/components/schemas/NexusAddress'
NexusAddress:
type: object
description: The NexusAddress supported by tax provider
required:
- countryCode
- country
- stateCode
- state
properties:
countryCode:
type: string
description: The country code of the Address following the ISO 3166-1 alpha-2 standard.
minLength: 2
maxLength: 2
country:
type: string
description: The country of the Address following standard.
minLength: 2
maxLength: 100
stateCode:
type: string
description: The state code of the Address following the ISO 3166-2 state/province code without the country prefix.
minLength: 2
maxLength: 2
state:
type: string
description: The state of the Address .
minLength: 2
maxLength: 100
NexusErrorResponse:
type: object
required:
- code
- message
- detail
properties:
code:
$ref: '#/components/schemas/NexusErrorCode'
message:
type: string
description: The description of the error with details about it's cause.
maxLength: 250
example: Invalid Credentials
detail:
type: string
description: The summary of the possible corrective action for the error.
maxLength: 250
example: Please provide a valid password.
helpUrl:
type: string
description: The link to the documentation for more information about the error and the corrective action.
format: uri
example: https://apidocs.chargebee.com#Authentication
traceId:
type: string
description: The reference id for the error used in logging and tracing.
maxLength: 50
example: f324123-a3cb1211-12312
NexusErrorCode:
type: string
description: The error codes classify the type of exception that occured during processing the request.
enum:
- INVALID_CREDENTIALS
- INVALID_REQUEST
- SERVICE_EXCEPTION
- SERVICE_UNAVAILABLE
- INVALID_Merchant_STATUS
- ENTITY_EMPTY
- ENTITY_NOT_FOUND
- ENTITY_RANGE_EXCEPTION
- ENTITY_CHAR_LIMIT_EXCEPTION
- ENTITY_INVALID_STATUS
parameters:
InvoiceIdPathParam:
in: path
name: invoiceId
required: true
schema:
type: string
maxLength: 50
description: "The unique identifier of the invoice at the Tax Service Adapter or Tax Service Provider."
CreditNoteIdPathParam:
in: path
name: creditNoteId
required: true
schema:
type: string
maxLength: 50
description: "The unique identifier of the credit note at the Tax Service Adapter or Tax Service Provider."
MerchantIdPathParam:
in: path
name: merchantId
required: true
schema:
type: string
maxLength: 50
description: The id of the merchantId provided to the tax provider.
responses:
Error400TaxEstimate:
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
examples:
Error400ResponseInvalidTaxCode:
$ref: '#/components/examples/Error400ResponseInvalidTaxCode'
Error400ResponseMissingCustomerAddress:
$ref: '#/components/examples/Error400ResponseMissingCustomerAddress'
Error400Invoice:
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
examples:
Error400ResponseInvalidTaxCode:
$ref: '#/components/examples/Error400ResponseInvalidTaxCode'
Error400ResponseMissingCustomerAddress:
$ref: '#/components/examples/Error400ResponseMissingCustomerAddress'
Error400CreditNote:
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
examples:
Error400ResponseInvalidCreditNoteId:
$ref: '#/components/examples/Error400ResponseInvalidCreditNoteId'
Error400ResponseMissingCustomerAddress:
$ref: '#/components/examples/Error400ResponseMissingCustomerAddress'
Error401:
description: Unauthenticated request.
Error403:
description: Unauthorized request.
Error404:
description: Not found.
Error429:
description: Too many requests.
Error500:
description: Unexpected error while processing request.
content:
application/json:
schema:
$ref: '#/components/schemas/BasicErrorResponse'
examples:
Error500:
$ref: '#/components/examples/Error500Response'
Error503:
description: Service is unhealthy.
content:
application/json:
schema:
$ref: '#/components/schemas/HealthCheckResponse'
example:
status: DOWN
version: 1.0.0
description: The service is unhealthy. Several components are down.
components:
- id: app-db1-memory
name: Application Database Memory Usage
type: DATABASE
status: UP
- id: tax-cb-adapter-server
name: Tax Adapter API Server
type: ADAPTER
status: DOWN
- id: tax-rest-server
name: Tax API Server
type: API
status: DOWN
time: '2022-11-01T10:42:08.131+05:30'
Error400Nexus:
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/NexusErrorResponse'
examples:
Error400ResponseMissingMerchantId:
$ref: '#/components/examples/Error400ResponseMissingMerchantId'
Error400ResponseInvalidMerchantId:
$ref: '#/components/examples/Error400ResponseInvalidMerchantId'
Error401Nexus:
description: Unauthenticated request.
content:
application/json:
schema:
$ref: '#/components/schemas/NexusErrorResponse'
examples:
Error401Nexus:
$ref: '#/components/examples/Error401NexusResponse'
Error403Nexus:
description: Forbidden request.
content:
application/json:
schema:
$ref: '#/components/schemas/NexusErrorResponse'
examples:
Error403Nexus:
$ref: '#/components/examples/Error403NexusResponse'
Error404Nexus:
description: Nexus Address List not found.
content:
application/json:
schema:
$ref: '#/components/schemas/NexusErrorResponse'
example:
code: INVALID_REQUEST
message: Nexus Address List not found..
detail: /merchandId/224342 is not available. Please check refundId.
Error500Nexus:
description: Unexpected error while fetching refund.
content:
application/json:
schema:
$ref: '#/components/schemas/NexusErrorResponse'
examples:
Error500Nexus:
$ref: '#/components/examples/Error500NexusResponse'
Error503Nexus:
description: Service unavailable.
content:
application/json:
schema:
$ref: '#/components/schemas/NexusErrorResponse'
examples:
Error503Nexus:
$ref: '#/components/examples/Error503NexusResponse'
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:
customerCode: customer_test
address:
line1: 59, Starlight Avenue
city: Newark
state: NJ
country: US
postalCode: '98712'
estimateDateTime: '2022-11-01T10:42:08.131+05:30'
currency: USD
lineItems:
- number: 1
itemCode: cbWatch
description: A winding watch.
quantity: 1
amount: 100
isTaxInclusive: false
taxCodeFields:
- 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-01T10:42:08.131+05:30'
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
taxCodeFields:
- 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
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:
customerCode: customer_test
address:
line1: 59, Starlight Avenue
city: Newark
state: NJ
country: US
postalCode: '98712'
estimateDateTime: '2022-11-01T10:42:08.131+05:30'
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:
customerCode: customer_test
address:
line1: 59, Starlight Avenue
city: Newark
state: NJ
country: US
postalCode: '98712'
estimateDateTime: '2022-11-01T10:42:08.131+05:30'
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:
customerCode: customer_test
address:
line1: 59, Starlight Avenue
city: Newark
state: NJ
country: US
postalCode: '98712'
exemptionFields:
- id: exemptionCode
value: ex_gg1s2149812312
estimateDateTime: '2022-11-01T10:42:08.131+05:30'
currency: USD
lineItems:
- number: 1
itemCode: cbWatch
description: A winding watch.
quantity: 1
amount: 110
isTaxInclusive: false
taxCodeFields:
- 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:
customerCode: customer_test
address:
line1: 59, Starlight Avenue
city: Newark
state: NJ
country: US
postalCode: '98712'
exemptionFields:
- id: exemptionCode
value: ex_gg1s2149812312
- id: category
value: category1
estimateDateTime: '2022-11-01T10:42:08.131+05:30'
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
taxCodeFields:
- 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-01T10:42:08.131+05:30'
currency: USD
seller:
address:
line1: 412 63rd South Avenue
city: Baltimore
state: MD
country: US
postalCode: '21230'
customer:
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
taxCodeFields:
- 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-01T10:42:08.131+05:30'
currency: USD
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'
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
taxCodeFields:
- 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
CreditNoteRequestFull:
description: A request to send a credit note to the Tax Service Adapter.
value:
creditNoteCode: inv_1235
invoiceCode: disney_001
creditNoteType: FULL
documentDateTime: '2022-11-01T10:42:08.131+05:30'
currency: USD
seller:
address:
line1: 412 63rd South Avenue
city: Baltimore
state: MD
country: US
postalCode: '21230'
customer:
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: disney_001
invoiceCode: inv_1235
status: PENDING
creditNoteType: FULL
documentDateTime: '2022-11-01T10:42:08.131+05:30'
currency: USD
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'
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
taxCodeFields:
- 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
Error400ResponseInvalidCreditNoteId:
summary: Invalid credit note id.
description: Credit note id is invalid.
value:
errors:
- code: INVALID_DATA
message: Credit note id is not valid.
entity: CreditNoteId
entityField: creditNoteId
Error400ResponseInvalidTaxCode:
summary: Invalid item tax code.
description: Item tax code is invalid.
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:
summary: Missing customer address.
description: Customer address is empty.
value:
errors:
- code: MISSING_REQUIRED_DATA
entity: Customer
entityField: customer.address
message: Customer address cannot be empty.
Error500Response:
summary: Unexpected error.
description: Unexpected error during processing the request.
value:
message: Unexpected error during processing the request.
AddressValidationValidRequest:
summary: Valid address request for full address verification
description: Valid address request
value:
address:
line1: 1000 main
line2: ''
line3: ''
city: Irvine
state: CA
country: US
postalCode: '92615'
AddressValidationInvalidRequest:
summary: Invalid address request for full address verification
description: Invalid address request
value:
address:
line1: 1000 MAIN ST
line2: ''
line3: ''
city: IRVINE
state: CA
country: US
postalCode: '92614'
AddressValidationValidResponse:
summary: Valid address verification response
description: Valid address verification response when address is validated successfully
value:
status: VALID
AddressValidationInvalidResponse:
summary: Invalid address verification response
description: The address provided for verification was Invalid
value:
status: INVALID
CheckAddressTaxabilityValidRequest-Option1:
summary: Taxable address request (city + state + country + postalCode)
description: Taxable address with combinataion of city,state,country,postalCode sent in a post request
value:
address:
line1: ''
line2: ''
line3: ''
city: IRVINE
state: CA
country: US
postalCode: '92614'
CheckAddressTaxabilityInvalidRequest-Option1:
summary: Non-taxable address request (city + state + country + postalCode)
description: Non-taxable address with combinataion of city,state,country,postalCode sent in a post request
value:
address:
line1: ''
line2: ''
line3: ''
city: Irvine
state: CA
country: US
postalCode: '88777'
CheckAddressTaxabilityValidResponse-Option1:
summary: Taxable address Response (city + state + country + postalCode)
description: Valid Respose based on combinataion of city,state,country,postalCode sent in a post request
value:
isTaxable: true
CheckAddressTaxabilityInalidResponse-Option1:
summary: Non-taxable address Response (city + state + country + postalCode)
description: Invalid Response based on combinataion of city,state,country,postalCode sent in a post request
value:
isTaxable: false
CheckAddressTaxabilityValidRequest-Option2:
summary: Taxable address request (city + country + postalCode)
description: Taxable address with combinataion of city,country,postalCode sent in a post request
value:
address:
line1: ''
line2: ''
line3: ''
state: ''
city: Irvine
country: US
postalCode: '92615'
CheckAddressTaxabilityInvalidRequest-Option2:
summary: Non-taxable address request (city + country + postalCode)
description: Shows a non-taxable address sent in a post request
value:
address:
line1: ''
line2: ''
line3: ''
state: ''
city: Irvine
country: US
postalCode: '83835'
CheckAddressTaxabilityValidResponse-Option2:
summary: Taxable address response (city + country + postalCode)
description: Valid Response based on combinataion of city,country,postalCode sent in a post request
value:
isTaxable: true
CheckAddressTaxabilityInalidResponse-Option2:
summary: Non-taxable address response (city + country + postalCode)
description: Invalid response based on combinataion of city,country,postalCode sent in a post request
value:
isTaxable: false
CheckAddressTaxabilityValidRequest-Option3:
summary: Taxable address request (postalCode)
description: Taxable address with combinataion of city,state,postalCode sent in a post request
value:
address:
line1: ''
line2: ''
line3: ''
city: ''
state: ''
country: ''
postalCode: '92614'
CheckAddressTaxabilityInvalidRequest-Option3:
summary: Non-taxable address request (postalCode)
description: Non-taxable address with combinataion of city,state,postalCode sent in a post request
value:
address:
line1: ''
line2: ''
line3: ''
city: ''
state: ''
country: ''
postalCode: '45645'
CheckAddressTaxabilityValidResponse-Option3:
summary: Taxable address response (postalCode)
description: Valid response based on combinataion of city,state,postalCode sent in a post request
value:
isTaxable: true
CheckAddressTaxabilityInalidResponse-Option3:
summary: Non-taxable address response (postalCode)
description: Non-taxable address response based on combinataion of city,state,postalCode sent in a post request
value:
isTaxable: false
FetchNexusAddressListResponseSimple:
summary: A valid nexus address list
description: Fetching the nexus address list based on one merchant.
value:
-
countryCode: US
country: United States
stateCode: CA
state: California
-
countryCode: US
country: United States
stateCode: NY
state: New York
-
countryCode: US
country: United States
stateCode: WA
state: Washington
Error400ResponseMissingMerchantId:
summary: Empty merchant id.
description: Merchant id is empty.
value:
code: INVALID_REQUEST
message: Merchant id cannot be empty.
detail: Please provide a valid Merchant id.
Error400ResponseInvalidMerchantId:
summary: Empty merchant id.
description: Merchant id is invalid.
value:
code: INVALID_REQUEST
message: Invalid Merchant id.
detail: Please provide a valid erchant id.
Error401NexusResponse:
summary: Unauthenticated.
description: An unauthenticated request.
value:
code: INVALID_CREDENTIALS
message: Authentication failied due to invalid credentials.
detail: Please provider correct authentication API Key.
Error403NexusResponse:
summary: Forbidden.
description: Forbidden request.
value:
code: INVALID_CREDENTIALS
message: Access denied to resource.
detail: You are not authrorized to access /nexus.
Error500NexusResponse:
summary: Unexpected error.
description: Unexpected error during processing the request.
value:
code: SERVICE_EXCEPTION
message: Unexpected error during processing the request.
traceId: 134C0C5B-5301-48AC-99FB-30C62011C598
detail: Please contact support@chargebee.com with the traceId.
Error503NexusResponse:
summary: Service unavailable.
description: Service is not available to process requests.
value:
code: SERVICE_UNAVAILABLE
message: Tax provider system is not available.
detail: Tax provider system is under system maintenance. Please try again later.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
apiKey:
type: apiKey
description: Bearer token based authentication.
name: bearer
in: header
security:
- bearerAuth: []
- apiKey: []