Create credit note - Chargebee Partner docs

POST

credit-notes

curl --request POST \
  --url https://rest.taxes.provider.com/api/v1/credit-notes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "creditNoteCode": "cn_2023_11_24_178",
  "invoiceCode": "inv_2023_11_30_78",
  "invoiceId": "disney_001",
  "creditNoteType": "FULL",
  "documentDateTime": "2022-11-01T05:12:08.131Z",
  "taxDateTime": "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
}'

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

Authorizations

Authorization

string

header

required

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

Body

application/json

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.

creditNoteCode

string

required

The unique identifier of the credit note in Chargebee.

Maximum length: 50

creditNoteType

enum<string>

required

Whether the credit note was created for the full amount on the invoice or only for a part of the invoice amount.

Available options:

FULL,

PARTIAL

documentDateTime

string

required

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 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.

currency

string

required

The currency in the ISO-4217 format.

Required string length: 3

seller

object

required

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

seller.address

object

required

Represents the address used for validation.

Example:

{
  "country": "country",
  "city": "city",
  "postalCode": "postalCode",
  "state": "state",
  "line3": "line3",
  "line2": "line2",
  "line1": "line1"
}

seller.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

seller.hasNexus

boolean

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

Example:

{
  "address": {
    "country": "country",
    "city": "city",
    "postalCode": "postalCode",
    "state": "state",
    "line3": "line3",
    "line2": "line2",
    "line1": "line1"
  },
  "taxRegistrationNumber": "taxRegistrationNumber",
  "hasNexus": true
}

customer

object

required

The details of the Customer.

customer.customerCode

string

required

The unique identifier for the Customer in Chargebee.

Maximum length: 50

customer.address

object

required

Represents the address used for validation.

Example:

{
  "country": "country",
  "city": "city",
  "postalCode": "postalCode",
  "state": "state",
  "line3": "line3",
  "line2": "line2",
  "line1": "line1"
}

customer.name

string

The name of the Customer in Chargebee.

Maximum length: 50

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

customer.taxIdentifiers

object[]

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

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.

Example:

{
  "paymentCountryCode": "paymentCountryCode",
  "bin": "bin",
  "ip": "ip"
}

Example:

{
  "address": {
    "country": "country",
    "city": "city",
    "postalCode": "postalCode",
    "state": "state",
    "line3": "line3",
    "line2": "line2",
    "line1": "line1"
  },
  "name": "name",
  "customerCode": "customerCode",
  "taxRegistrationNumber": "taxRegistrationNumber",
  "hasNexus": true,
  "locationEvidence": {
    "paymentCountryCode": "paymentCountryCode",
    "bin": "bin",
    "ip": "ip"
  },
  "taxIdentifiers": [
    { "id": "id", "value": "value" },
    { "id": "id", "value": "value" },
    { "id": "id", "value": "value" },
    { "id": "id", "value": "value" },
    { "id": "id", "value": "value" }
  ]
}

total

number

required

The total amount of the credit note. total can be expressed as exemptAmount + taxableAmount + taxAmount.

exemptAmount

number

required

The amount exempted from tax.

discountAmount

number

required

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

taxableAmount

number

required

The amount upon which the tax is calculated.

taxAmount

number

required

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

invoiceCode

string

The unique identifier of the invoice in Chargebee to which this credit note belongs.

Maximum length: 50

invoiceId

string

The unique identifier of the invoice in the Tax Service Adapter or the Tax Service Provider.

taxDateTime

string

The date and time at which the tax was applicable 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 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.

roundingAmount

number

The rounding amount added to the total amount to account for fractional correction.

lineItems

object[]

The details of a line item.

lineItems.number

integer

required

Index or serial number of the line item.

Required range: x >= 1

lineItems.amount

number

required

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

lineItems.subtotal

number

required

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

lineItems.isTaxInclusive

boolean

required

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

lineItems.isTaxable

boolean

required

Indicates whether this line item is taxable.

lineItems.exemptAmount

number

required

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

lineItems.discountAmount

number

required

The discount applied to this line item.

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.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.taxes

object[]

required

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

The details of tax applied under a specific jurisdiction.

lineItems.taxes.number

integer

required

Index or serial number of this tax line item.

Required range: x >= 1

lineItems.taxes.jurisdiction

object

required

The tax jurisdiction details.

Example:

{
  "code": "code",
  "name": "name",
  "type": null
}

lineItems.taxes.name

string

required

The name of the tax applied.

Example:

"GST"

lineItems.taxes.rate

number

required

The tax rate expressed in percentage.

Required range: x <= 100

lineItems.taxes.taxableAmount

number

required

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

lineItems.taxes.taxAmount

number

required

The tax payable for the line item under this jurisdiction.

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. If entity_type is adhoc, the itemCode parameter will be set to adhoc_charge.

Maximum length: 50

lineItems.description

string

The description of the line item.

Maximum length: 250

lineItems.quantity

number

The quantity associated with this line item.

Required range: x >= 0

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

lineItems.taxIdentifiers

object[]

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

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.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

Example:

"The customer is exempt from taxes."

lineItems.isPartialTax

boolean

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

Response

201

application/json

Credit note created successfully.

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.

creditNoteId

string

required

The unique identifier of the credit note at the Tax Service Provider or Tax Service Adapter.

creditNoteCode

string

required

The unique identifier of the credit note in Chargebee.

Maximum length: 50

creditNoteType

enum<string>

required

Whether the credit note was created for the full amount on the invoice or only for a part of the invoice amount.

Available options:

FULL,

PARTIAL

documentDateTime

string

required

status

enum<string>

required

Status of the invoice document.

Available options:

PENDING,

COMMITTED,

VOIDED

currency

string

required

The currency in the ISO-4217 format.

Required string length: 3

seller

object

required

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

seller.address

object

required

Represents the address used for validation.

Example:

{
  "country": "country",
  "city": "city",
  "postalCode": "postalCode",
  "state": "state",
  "line3": "line3",
  "line2": "line2",
  "line1": "line1"
}

seller.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

seller.hasNexus

boolean

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

Example:

{
  "address": {
    "country": "country",
    "city": "city",
    "postalCode": "postalCode",
    "state": "state",
    "line3": "line3",
    "line2": "line2",
    "line1": "line1"
  },
  "taxRegistrationNumber": "taxRegistrationNumber",
  "hasNexus": true
}

customer

object

required

The details of the Customer.

customer.customerCode

string

required

The unique identifier for the Customer in Chargebee.

Maximum length: 50

customer.address

object

required

Represents the address used for validation.

Example:

{
  "country": "country",
  "city": "city",
  "postalCode": "postalCode",
  "state": "state",
  "line3": "line3",
  "line2": "line2",
  "line1": "line1"
}

customer.name

string

The name of the Customer in Chargebee.

Maximum length: 50

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

customer.taxIdentifiers

object[]

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

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.

Example:

{
  "paymentCountryCode": "paymentCountryCode",
  "bin": "bin",
  "ip": "ip"
}

Example:

{
  "address": {
    "country": "country",
    "city": "city",
    "postalCode": "postalCode",
    "state": "state",
    "line3": "line3",
    "line2": "line2",
    "line1": "line1"
  },
  "name": "name",
  "customerCode": "customerCode",
  "taxRegistrationNumber": "taxRegistrationNumber",
  "hasNexus": true,
  "locationEvidence": {
    "paymentCountryCode": "paymentCountryCode",
    "bin": "bin",
    "ip": "ip"
  },
  "taxIdentifiers": [
    { "id": "id", "value": "value" },
    { "id": "id", "value": "value" },
    { "id": "id", "value": "value" },
    { "id": "id", "value": "value" },
    { "id": "id", "value": "value" }
  ]
}

discountAmount

number

required

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

exemptAmount

number

required

The amount exempted from tax.

taxableAmount

number

required

The amount upon which the tax is calculated.

taxAmount

number

required

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

total

number

required

The total amount of the credit note. total can be expressed as exemptAmount + taxableAmount + taxAmount.

lineItems

object[]

required

The details of a line item.

lineItems.number

integer

required

Index or serial number of the line item.

Required range: x >= 1

lineItems.amount

number

required

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

lineItems.subtotal

number

required

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

lineItems.isTaxInclusive

boolean

required

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

lineItems.isTaxable

boolean

required

Indicates whether this line item is taxable.

lineItems.exemptAmount

number

required

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

lineItems.discountAmount

number

required

The discount applied to this line item.

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.total

number

required

lineItems.taxes

object[]

required

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

The details of tax applied under a specific jurisdiction.

lineItems.taxes.number

integer

required

Index or serial number of this tax line item.

Required range: x >= 1

lineItems.taxes.jurisdiction

object

required

The tax jurisdiction details.

Example:

{
  "code": "code",
  "name": "name",
  "type": null
}

lineItems.taxes.name

string

required

The name of the tax applied.

Example:

"GST"

lineItems.taxes.rate

number

required

The tax rate expressed in percentage.

Required range: x <= 100

lineItems.taxes.taxableAmount

number

required

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

lineItems.taxes.taxAmount

number

required

The tax payable for the line item under this jurisdiction.

lineItems.itemCode

string

Maximum length: 50

lineItems.description

string

The description of the line item.

Maximum length: 250

lineItems.quantity

number

The quantity associated with this line item.

Required range: x >= 0

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

lineItems.taxIdentifiers

object[]

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

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.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

Example:

"The customer is exempt from taxes."

lineItems.isPartialTax

boolean

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

invoiceCode

string

The unique identifier of the invoice in Chargebee to which this credit note belongs.

Maximum length: 50

invoiceId

string

The unique identifier of the invoice in the Tax Service Adapter or the Tax Service Provider.

taxDateTime

string

subtotal

number

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

roundingAmount

number

The rounding amount added to the total amount to account for fractional correction.

Void Invoice Retrieve credit note

curl --request POST \
  --url https://rest.taxes.provider.com/api/v1/credit-notes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "creditNoteCode": "cn_2023_11_24_178",
  "invoiceCode": "inv_2023_11_30_78",
  "invoiceId": "disney_001",
  "creditNoteType": "FULL",
  "documentDateTime": "2022-11-01T05:12:08.131Z",
  "taxDateTime": "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
}'

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

API Reference

Authorizations

Body

Response