Estimate tax - Chargebee Partner docs

POST

tax-estimate

curl --request POST \
  --url https://rest.taxes.provider.com/api/v1/tax-estimate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "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"
        }
      ]
    }
  ]
}'

{
  "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
        }
      ]
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

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.

currency

string

required

The currency in the ISO-4217 format.

Required string length: 3

customer

object

required

The details of the Customer.

customer.address

object

required

Represents the address used for validation.

customer.customerCode

string

required

The unique identifier for the Customer in Chargebee.

Maximum length: 50

customer.hasNexus

boolean

Determines whether a tax nexus exists between the Seller and the tax authority at the address provided.

customer.locationEvidence

object

Represent the properties for customer location evidence.

customer.name

string

The name of the Customer in Chargebee.

Maximum length: 50

customer.taxIdentifiers

object[]

It represents the information related to the customer's tax identifiers. This includes details such as exemption status etc.

customer.taxRegistrationNumber

string

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.

Maximum length: 30

estimateDateTime

string

required

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 data types 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

lineItems

object[]

required

Contains the details of each line item in the tax estimation request.

seller

object

required

The details of the seller involved in the transaction including company code and address.

Response

200 - application/json

The response sent by the Tax Service Adapter to Chargebee for a tax estimation request.

currency

string

required

The currency in the ISO-4217 format.

Required string length: 3

customer

object

required

The details of the Customer.

customer.address

object

required

Represents the address used for validation.

customer.customerCode

string

required

The unique identifier for the Customer in Chargebee.

Maximum length: 50

customer.hasNexus

boolean

Determines whether a tax nexus exists between the Seller and the tax authority at the address provided.

customer.locationEvidence

object

Represent the properties for customer location evidence.

customer.name

string

The name of the Customer in Chargebee.

Maximum length: 50

customer.taxIdentifiers

object[]

It represents the information related to the customer's tax identifiers. This includes details such as exemption status etc.

customer.taxRegistrationNumber

string

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.

Maximum length: 30

discountAmount

number

required

The total discount applied. This is the sum of all lineItems.discount.

estimateDateTime

string

required

exemptAmount

number

required

The part of the subtotal that is exempted from tax.

lineItems

object[]

required

List of line item details for the tax estimation response.

lineItems.amount

number

required

The amount for this line item. This is unitPrice × quantity.

lineItems.discountAmount

number

required

The discount applied to this line item.

lineItems.exemptAmount

number

required

The part of this line item's subtotal that is exempted from tax.

lineItems.isTaxable

boolean

required

Indicates whether this line item is taxable.

lineItems.isTaxInclusive

boolean

required

Indicates whether the subtotal for this line item is inclusive of taxes.

lineItems.number

integer

required

Index or serial number of the line item.

Required range: x > 1

lineItems.subtotal

number

required

The amount after discounts for this line item. This is amount - discountAmount.

lineItems.taxableAmount

number

required

The part of this line item's subtotal that is taxable.

lineItems.taxAmount

number

required

The tax payable for this line item. This is the sum of all taxes.taxAmount for this line item.

lineItems.taxes

object[]

required

List of taxes applied for this line item under each jurisdiction.

lineItems.total

number

required

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.

lineItems.description

string

The description of the line item.

Maximum length: 250

lineItems.isPartialTax

boolean

Indicates if taxes were applied only partially for this line item.

lineItems.itemCode

string

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.

Maximum length: 50

lineItems.quantity

number

The quantity associated with this line item.

Required range: x > 0

lineItems.taxExemptReason

string

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.

Maximum length: 250

lineItems.taxExemptType

enum<string>

The tax exemption type for a line item. This is a mandatory parameter while applying tax exemption on any line-item.

Available options:

PRODUCT_EXEMPT,

CUSTOMER_EXEMPT,

REGION_EXEMPT,

REVERSE_CHARGE,

ZERO_RATE_TAX,

HIGH_VALUE_PHYSICAL_GOODS,

EXPORT,

ZERO_VALUE_ITEM,

TAX_NOT_CONFIGURED

lineItems.taxIdentifiers

object[]

The tax code fields of the product used for tax calculation.

lineItems.unitPrice

number

The unit price for this line item. In case of tiered pricing where the unit price varies for each quantity tier, this is the average unit price.

Required range: x > 0

seller

object

required

The details of the seller involved in the transaction including company code and address.

subtotal

number

required

The amount after discounts. This is the sum of all lineItems.subtotal.

taxableAmount

number

required

The part of the subtotal that is taxable.

taxAmount

number

required

The total tax payable. This is the sum of all lineItems.taxAmount.

total

number

required

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.

Check taxability Create Invoice

curl --request POST \
  --url https://rest.taxes.provider.com/api/v1/tax-estimate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "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"
        }
      ]
    }
  ]
}'

{
  "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
        }
      ]
    }
  ]
}

API Reference

Authorizations

Body

Response