Credit notes

Library

A Credit Note is a document that specifies the money owed by a business to its customer. The seller usually issues a Credit Note for the same or lower amount than the invoice, and then repays the money to the customer or set it off against other 'due' invoices.

Credit Note Types

Credit notes in Chargebee are categorized into three types: 1. adjustment: Adjustment credit notes are used to adjust the amount of an existing invoice in the payment_due or not_paid status. Use this type of credit note to reduce the invoice amount, typically as a discount to the customer.
Adjustment credit notes are automatically created in the following cases:

When an invoice is written off.
When a subscription is modified with proration enabled, and the invoice for the current term is in the payment_due or not_paid status. 2. refundable: Refundable credit notes allow you to return a certain amount to the customer. These credits can be:
Retained for automatic application on future invoices.
Applied to existing unpaid invoices.
Refunded to the customer. Refundable credit notes are automatically created in the following cases:
When an invoice is refunded.
When a subscription is changed or canceled with proration enabled, the invoice for the current term is in the paid status. Refundable credits are applied to future invoices or can be refunded to the original payment method. 3. store: Store credit notes are created for paid or partially_paid invoice status during subscription changes, such as upgrades, downgrades, or cancellations. Key characteristics of store credits:
No tax component is included at the time of creation.
A credit note document is generated, similar to refundable credits.
Store credits are applied before tax calculations on future invoices.

Note: If you have enabled consolidated invoicing , to know the subscriptions attached with a credit note you have to refer line_item's subscription_id . The credit note's subscription_id should not be used (which will be null if the credit note has lines from multiple subscriptions).

Sample credit note [ JSON ]

{
    "allocations": [],
    "amount_allocated": 0,
    "amount_available": 500,
    "amount_refunded": 0,
    "base_currency_code": "USD",
    "create_reason_code": "Product Unsatisfactory",
    "currency_code": "USD",
    "customer_id": "__test__KyVnHhSBWSy4m5e",
    "date": 1517501405,
    "deleted": false,
    "exchange_rate": 1,
    "fractional_correction": 0,
    "id": "__demo_cn__1",
    "line_item_discounts": [],
    "line_item_taxes": [],
    "line_items": [
        {
            "amount": 500,
            "customer_id": "__test__KyVnHhSBWSy4m5e",
            "date_from": 1517501405,
            "date_to": 1517501405,
            "description": "Support Charge",
            "discount_amount": 0,
            "entity_type": "adhoc",
            "id": "li___test__KyVnHhSBWSyHE5r",
            "is_taxed": false,
            "item_level_discount_amount": 0,
            "object": "line_item",
            "pricing_model": "flat_fee",
            "quantity": 1,
            "tax_amount": 0,
            "tax_exempt_reason": "tax_not_configured",
            "unit_amount": 500
        }
    ],
    "linked_refunds": [],
    "object": "credit_note",
    "price_type": "tax_exclusive",
    "reason_code": "product_unsatisfactory",
    "reference_invoice_id": "__demo_inv__1",
    "resource_version": 1517501405000,
    "round_off_amount": 0,
    "status": "refund_due",
    "sub_total": 500,
    "taxes": [],
    "total": 500,
    "type": "refundable",
    "updated_at": 1517501405
}

API Index URL

https://{site}.chargebee.com/api/v2/credit_notes

id

string, max chars=50

Credit-note id.

customer_id

string, max chars=50

The identifier of the customer this credit note belongs to.

subscription_id

optional, string, max chars=50

The identifier of the subscription this Credit Note belongs to. Note: If consolidated invoicing is enabled, to know the subscriptions attached with this Credit Note you have to refer line_item's subscription_id. This attribute should not be used (which will be null if this credit note has lines from multiple subscriptions).

reference_invoice_id

optional, string, max chars=50

The identifier of the invoice against which this Credit Note is issued

type

enumerated string

The credit note type. Learn more about credit note types.

Possible values are

reason_code

optional, enumerated string

The reason for issuing this credit note. The following reason codes are supported now[Deprecated; use the create_reason_code parameter instead]

Possible values are

status

enumerated string

The credit note status.

Possible values are

vat_number

optional, string, max chars=20

VAT number of the customer for whom this credit note is raised.

date

optional, timestamp(UTC) in seconds

The date the credit note is issued.

price_type

enumerated string, default=tax_exclusive

The price type of the credit note.

Possible values are

currency_code

string, max chars=3

The currency code (ISO 4217 format) for the credit note

total

optional, in cents, default=0, min=0

Credit Note amount in cents.

amount_allocated

optional, in cents, default=0, min=0

The amount allocated to invoices from the credit note.

amount_refunded

optional, in cents, default=0, min=0

The refunds issued from this credit note.

amount_available

optional, in cents, default=0, min=0

The yet to be used credits of this credit note.

refunded_at

optional, timestamp(UTC) in seconds

The time this credit note gets fully used. Please note that this field is not present when partial refunds are issued.

voided_at

optional, timestamp(UTC) in seconds

Timestamp indicating the date and time this credit note gets voided.

generated_at

optional, timestamp(UTC) in seconds

The date/time when the credit note was raised. This date/time can be backdated, which means that the date/time can be earlier than the date/time the credit note was created.

resource_version

optional, long

Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.

updated_at

optional, timestamp(UTC) in seconds

Timestamp indicating when this credit note was last updated. This attribute will be present only if the resource has been updated after 2016-09-28.

channel

optional, enumerated string

The subscription channel this object originated from and is maintained in.

Possible values are

line_items_next_offset

optional, string, max chars=1000

This attribute is returned only if additional resources are available. Use this value as the input parameter for line_items_offset to retrieve the next set of resources.

Note:

Applicable only when Enterprise-scale Invoicing is enabled.
Enterprise-scale Invoicing is currently in Private Beta. Please reach out to Chargebee Support to enable this feature.

sub_total

in cents, min=0

The Credit Note sub-total

sub_total_in_local_currency

optional, in cents, min=0

Invoice subtotal in the currency of the place of supply.

total_in_local_currency

optional, in cents, min=0

Total invoice amount in the currency of the place of supply.

local_currency_code

optional, string, max chars=3

The currency code (ISO 4217 format) of the place of supply in which VAT needs to be converted and displayed.

round_off_amount

optional, in cents, min=-99, max=99

Indicates the rounded-off amount. For example, if your invoice amount is $99.99, and the amount is rounded off to $100.00, in this case, $100.00 is your invoice amount, $0.01 is the round_off_amount. If there is no round-off amount , it will display 0 .

fractional_correction

optional, in cents, min=-50000, max=50000

Indicates the fractional correction amount.

deleted

boolean

Indicates that this resource has been deleted.

tax_category

optional, string

Specifies the customer's category for the Goods and Services Tax (GST). This field is returned only if you've configured GST for the India region.

local_currency_exchange_rate

optional, bigdecimal, min=1E-9, max=999999999.999999999

This parameter represents the exchange rate as a relative price of the base currency that appears as local currency in invoices and credit notes. The local currency exchange rate specifically refers to the exchange rate of a country's currency when converting it to another currency.

For example, if you want to convert US dollars to euros, the local currency exchange rate would be the rate at which you can convert US dollars to euros.

create_reason_code

optional, string, max chars=100

Reason code for creating the credit note. Must be one from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Credit Notes > Create Credit Note. Must be passed if set as mandatory in the app. The codes are case-sensitive

vat_number_prefix

optional, string, max chars=10

An overridden value for the first two characters of the full VAT number. Only applicable specifically for customers with billing_address

country as XI (which is United Kingdom - Northern Ireland ).

When you have enabled EU VAT in 2021 or have manually enabled the Brexit configuration, you have the option of setting billing_address

country as XI. That's the code for United Kingdom - Northern Ireland. The first two characters of the VAT number in such a case is XI by default. However, if the VAT number was registered in UK, the value should be GB. Set vat_number_prefix to GB for such cases.

business_entity_id

optional, string, max chars=50

The unique ID of the business entity of this credit_note. This is always the same as the business entity of the invoice referred to by reference_invoice_id.

GROUPED: line_items | line_item_tiers | line_item_discounts | line_item_taxes | line_item_addresses

line_items
Show attributes [+]

optional, list of line_item

The line items of this credit note

Line item attributes

id

optional, string, max chars=40

Uniquely identifies a line_item

subscription_id

optional, string, max chars=50

A unique identifier for the subscription this line item belongs to.

date_from

timestamp(UTC) in seconds

Start date of this line item.

date_to

timestamp(UTC) in seconds

End date of this line item.

unit_amount

in cents

Unit amount of the line item.

quantity

optional, integer, default=1

Quantity of the recurring item which is represented by this line item. For metered line items, this value is updated from usages once when the invoice is generated as pending and finally when the invoice is closed .

amount

optional, in cents

Total amount of this line item. Typically equals to unit amount x quantity

pricing_model

optional, enumerated string

The pricing scheme for this item price.

Possible values are

is_taxed

boolean, default=false

Specifies whether this line item is taxed or not

tax_amount

optional, in cents, default=0, min=0

The tax amount charged for this item

tax_rate

optional, double, min=0.0, max=100.0

Rate of tax used to calculate tax for this lineitem

unit_amount_in_decimal

optional, string, max chars=39

The decimal representation of the unit amount of the line_item. The value is in major units of the currency. Returned when the line_item is quantity-based and multi-decimal pricing is enabled.

quantity_in_decimal

optional, string, max chars=33

The decimal representation of the quantity of this line_item. Returned when the line_item is quantity-based and multi-decimal pricing is enabled.

amount_in_decimal

optional, string, max chars=39

The decimal representation of the amount for the line_item , in major units of the currency. Typically equals to unit_amount_in_decimal x quantity_in_decimal. Returned when multi-decimal pricing is enabled.

discount_amount

optional, in cents, min=0

Total discounts for this line

item_level_discount_amount

optional, in cents, min=0

Line Item-level discounts for this line.

metered

optional, boolean

is_percentage_pricing

optional, boolean

reference_line_item_id

optional, string, max chars=40

Invoice Reference Line Item ID

description

string, max chars=250

Detailed description about this line item.

entity_description

optional, string, max chars=500

Detailed description about this item.

entity_type

enumerated string

Specifies the modelled entity this line item is based on.

Possible values are

tax_exempt_reason

optional, enumerated string

The reason due to which the line item price/amount is exempted from tax.

Possible values are

entity_id

optional, string, max chars=100

The identifier of the modelled entity this line item is based on. Will be null for 'adhoc' entity type

customer_id

optional, string, max chars=100

A unique identifier for the customer this line item belongs to

line_item_tiers
Show attributes [+]

optional, list of line_item_tier

The list of tiers applicable for this line item

Line item tier attributes

line_item_id

optional, string, max chars=40

Uniquely identifies a line_item

starting_unit

integer, min=0

The lower limit of a range of units for the tier

ending_unit

optional, integer

The upper limit of a range of units for the tier

quantity_used

integer, min=0

The number of units purchased in a range.

unit_amount

in cents, min=0

The price of the tier if the charge model is a stairtstep pricing , or the price of each unit in the tier if the charge model is tiered /volume pricing.

starting_unit_in_decimal

optional, string, max chars=33

The decimal representation of the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as ending_unit_in_decimal of the next lower tier. Returned only when the line_items.pricing_model is tiered , volume or stairstep and multi-decimal pricing is enabled.

ending_unit_in_decimal

optional, string, max chars=33

The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the starting_unit_in_decimal of the next higher tier. Returned only when the line_items.pricing_model is tiered , volume or stairstep and multi-decimal pricing is enabled.

quantity_used_in_decimal

optional, string, max chars=33

The decimal representation of the quantity purchased from this tier. Returned when the line_item is quantity-based and multi-decimal pricing is enabled.

unit_amount_in_decimal

optional, string, max chars=40

The decimal representation of the per-unit price for the tier when the pricing_model is tiered or volume. When the pricing_model is stairstep , it is the decimal representation of the total price for line_item. The value is in major units of the currency. Returned when the line_item is quantity-based and multi-decimal pricing is enabled.

pricing_type

optional, enumerated string

Pricing type for the tier.

Possible values are

package_size

optional, integer, min=1

Package size for the tier when pricing type is package. Specify the number of units that make up one package. For example, if 1000 API hits are grouped into a single package, set the package size to 1000.

line_item_discounts
Show attributes [+]

optional, list of line_item_discount

The list of discount(s) applied for each line item of this credit note.

line_item_taxes
Show attributes [+]

optional, list of line_item_tax

The list of taxes applied on line items

Line item tax attributes

line_item_id

optional, string, max chars=40

The unique reference id of the line item for which the tax is applicable

tax_name

string, max chars=100

The name of the tax applied

tax_rate

double, default=0.0, min=0.0, max=100.0

The rate of tax used to calculate tax amount

date_to

optional, timestamp(UTC) in seconds

Indicates the service period end of the tax rate for the line item.

date_from

optional, timestamp(UTC) in seconds

Indicates the service period start of the tax rate for the line item.

prorated_taxable_amount

optional, bigdecimal, min=-1000000000, max=999999999.999999999

Indicates the prorated line item amount in cents.

is_partial_tax_applied

optional, boolean

Indicates if tax is applied only on a portion of the line item amount.

is_non_compliance_tax

optional, boolean

Indicates the non-compliance tax that should not be reported to the jurisdiction.

taxable_amount

in cents, min=0

Indicates the actual portion of the line item amount that is taxable.

tax_amount

in cents, min=0

The tax amount. This is set to the corresponding value on the invoice (invoice.line_item_taxes[i].tax_amount), prorated by the ratio of credit_note.total to invoice.total.

tax_juris_type

optional, enumerated string

The type of tax jurisdiction

Possible values are

tax_juris_name

optional, string, max chars=250

The name of the tax jurisdiction

tax_juris_code

optional, string, max chars=250

The tax jurisdiction code

tax_amount_in_local_currency

optional, in cents, min=0

Total tax amount in the currency of the place of supply. This is applicable only for Invoice and Credit Notes API.

local_currency_code

optional, string, max chars=3

The currency code (ISO 4217 format) of the place of supply in which VAT needs to be converted and displayed. This is applicable only for Invoice and Credit Notes API.

line_item_addresses
Show attributes [+]

optional, list of line_item_address

The list of addresses used for tax calculation on line items.

Line item address attributes

line_item_id

optional, string, max chars=40

Line item reference

first_name

optional, string, max chars=150

First name of the customer

last_name

optional, string, max chars=150

Last name of the customer

email

optional, string, max chars=70

Email address of the customer

company

optional, string, max chars=250

Name of the company

phone

optional, string, max chars=50

Phone number of the customer

line1

optional, string, max chars=150

Address line 1

line2

optional, string, max chars=150

Address line 2

line3

optional, string, max chars=150

Address line 3

city

optional, string, max chars=50

Name of the city

state_code

optional, string, max chars=50

The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ ). For Tamil Nadu (India), set as TN (not IN-TN ). For British Columbia (Canada), set as BC (not CA-BC ).

state

optional, string, max chars=50

State or Province

country

optional, string, max chars=50

The billing address of the customer, specified as an ISO 3166 alpha-2 code. Entering an invalid code will return an error.

If EU VAT (2021 or later) or Brexit configuration is enabled, 'United Kingdom-Northern Ireland' is a valid option.

zip

optional, string, max chars=20

Zip or postal code. The number of characters is validated according to the rules specified here .

validation_status

optional, enumerated string, default=not_validated

The address verification status.

Possible values are

discounts
Show attributes [+]

optional, list of discount

The list of discounts applied to this credit note

Discount attributes

amount

in cents, min=0

The amount deducted. The format of this value depends on the kind of currency .

description

optional, string, max chars=250

Description for this deduction.

line_item_id

optional, string, max chars=40

The unique id of the line item that this deduction is for. Is required when discounts[entity_type] is item_level_coupon or document_level_coupon .

entity_type

enumerated string

The type of deduction and the amount to which it is applied.

Possible values are

discount_type

optional, enumerated string

The type of discount that is applied to the line item. Relevant only when discounts[entity_type] is one of item_level_discount , item_level_coupon , document_level_discount , or document_level_coupon

Possible values are

entity_id

optional, string, max chars=100

When the deduction is due to a coupon or a discount , then this is the id of the coupon or discount.

coupon_set_code

optional, string, max chars=50

The coupon code , if applicable, used to provide the discount. The coupon.id is available in entity_id .

taxes
Show attributes [+]

optional, list of tax

The tax-lines of this credit note

tax_origin
Show attributes [+]

optional, tax_origin

contains information about the tax details which is applied on the invoice.

linked_refunds
Show attributes [+]

optional, list of credit_note_transaction

Payment Refunds issued from this credit note

linked_tax_withheld_refunds
Show attributes [+]

optional, list of linked_tax_withheld_refund

The details of refunds recorded against the invoice.linked_taxes_withheld component of the invoice associated with this credit_note.

allocations
Show attributes [+]

optional, list of applied_credit

Invoice allocations made from this credit note.

shipping_address
Show attributes [+]

optional, shipping_address

Shipping address for the credit note.

Shipping address attributes

first_name

optional, string, max chars=150

The first name of the contact.

last_name

optional, string, max chars=150

The last name of the contact.

email

optional, string, max chars=70

The email address.

company

optional, string, max chars=250

The company name.

phone

optional, string, max chars=50

The phone number.

line1

optional, string, max chars=150

Address line 1

line2

optional, string, max chars=150

Address line 2

line3

optional, string, max chars=150

Address line 3

city

optional, string, max chars=50

The name of the city.

state_code

optional, string, max chars=50

state

optional, string, max chars=50

The state/province name.

country

optional, string, max chars=50

The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code .

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom - Northern Ireland) is available as an option.

zip

optional, string, max chars=20

Zip or postal code. The number of characters is validated according to the rules specified here .

validation_status

optional, enumerated string, default=not_validated

The address verification status.

Possible values are

billing_address
Show attributes [+]

optional, billing_address

Billing address for the credit note.

Billing address attributes

first_name

optional, string, max chars=150

The first name of the billing contact.

last_name

optional, string, max chars=150

The last name of the billing contact.

email

optional, string, max chars=70

The email address.

company

optional, string, max chars=250

The company name.

phone

optional, string, max chars=50

The phone number.

line1

optional, string, max chars=150

Address line 1

line2

optional, string, max chars=150

Address line 2

line3

optional, string, max chars=150

Address line 3

city

optional, string, max chars=50

The name of the city.

state_code

optional, string, max chars=50

state

optional, string, max chars=50

State or Province

country

optional, string, max chars=50

The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code .

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom - Northern Ireland) is available as an option.

zip

optional, string, max chars=20

Zip or postal code. The number of characters is validated according to the rules specified here .

validation_status

optional, enumerated string, default=not_validated

The address verification status.

Possible values are

einvoice
Show attributes [+]

optional, einvoice

An e-invoice or electronic invoice is a structured representation of an invoice that is interoperable between computerized invoicing systems. Depending on the country, e-invoicing can be necessary to meet financial/taxation authority regulations.

site_details_at_creation
Show attributes [+]

optional, site_details_at_creation

It contains site-specific information, including timezone and organisational address.

id

string, max chars=50

Credit-note id.

customer_id

string, max chars=50

The identifier of the customer this credit note belongs to.

subscription_id

optional, string, max chars=50

reference_invoice_id

optional, string, max chars=50

The identifier of the invoice against which this Credit Note is issued

type

enumerated string

The credit note type. Learn more about credit note types.

Possible values are

reason_code

optional, enumerated string

The reason for issuing this credit note. The following reason codes are supported now[Deprecated; use the create_reason_code parameter instead]

Possible values are

status

enumerated string

The credit note status.

Possible values are

vat_number

optional, string, max chars=20

VAT number of the customer for whom this credit note is raised.

date

optional, timestamp(UTC) in seconds

The date the credit note is issued.

price_type

enumerated string, default=tax_exclusive

The price type of the credit note.

Possible values are

currency_code

string, max chars=3

The currency code (ISO 4217 format) for the credit note

total

optional, in cents, default=0, min=0

Credit Note amount in cents.

amount_allocated

optional, in cents, default=0, min=0

The amount allocated to invoices from the credit note.

amount_refunded

optional, in cents, default=0, min=0

The refunds issued from this credit note.

amount_available

optional, in cents, default=0, min=0

The yet to be used credits of this credit note.

refunded_at

optional, timestamp(UTC) in seconds

The time this credit note gets fully used. Please note that this field is not present when partial refunds are issued.

voided_at

optional, timestamp(UTC) in seconds

Timestamp indicating the date and time this credit note gets voided.

generated_at

optional, timestamp(UTC) in seconds

The date/time when the credit note was raised. This date/time can be backdated, which means that the date/time can be earlier than the date/time the credit note was created.

resource_version

optional, long

updated_at

optional, timestamp(UTC) in seconds

Timestamp indicating when this credit note was last updated. This attribute will be present only if the resource has been updated after 2016-09-28.

channel

optional, enumerated string

The subscription channel this object originated from and is maintained in.

Possible values are

line_items_next_offset

optional, string, max chars=1000

This attribute is returned only if additional resources are available. Use this value as the input parameter for line_items_offset to retrieve the next set of resources.

Note:

Applicable only when Enterprise-scale Invoicing is enabled.
Enterprise-scale Invoicing is currently in Private Beta. Please reach out to Chargebee Support to enable this feature.

sub_total

in cents, min=0

The Credit Note sub-total

sub_total_in_local_currency

optional, in cents, min=0

Invoice subtotal in the currency of the place of supply.

total_in_local_currency

optional, in cents, min=0

Total invoice amount in the currency of the place of supply.

local_currency_code

optional, string, max chars=3

The currency code (ISO 4217 format) of the place of supply in which VAT needs to be converted and displayed.

round_off_amount

optional, in cents, min=-99, max=99

fractional_correction

optional, in cents, min=-50000, max=50000

Indicates the fractional correction amount.

deleted

boolean

Indicates that this resource has been deleted.

tax_category

optional, string

Specifies the customer's category for the Goods and Services Tax (GST). This field is returned only if you've configured GST for the India region.

local_currency_exchange_rate

optional, bigdecimal, min=1E-9, max=999999999.999999999

For example, if you want to convert US dollars to euros, the local currency exchange rate would be the rate at which you can convert US dollars to euros.

create_reason_code

optional, string, max chars=100

vat_number_prefix

optional, string, max chars=10

An overridden value for the first two characters of the full VAT number. Only applicable specifically for customers with billing_address

country as XI (which is United Kingdom - Northern Ireland ).

When you have enabled EU VAT in 2021 or have manually enabled the Brexit configuration, you have the option of setting billing_address

business_entity_id

optional, string, max chars=50

The unique ID of the business entity of this credit_note. This is always the same as the business entity of the invoice referred to by reference_invoice_id.

discounts

optional, list of discount

The list of discounts applied to this credit note

taxes

optional, list of tax

The tax-lines of this credit note

tax_origin

optional, tax_origin

contains information about the tax details which is applied on the invoice.

linked_refunds

optional, list of credit_note_transaction

Payment Refunds issued from this credit note

linked_tax_withheld_refunds

optional, list of linked_tax_withheld_refund

The details of refunds recorded against the invoice.linked_taxes_withheld component of the invoice associated with this credit_note.

allocations

optional, list of applied_credit

Invoice allocations made from this credit note.

shipping_address

optional, shipping_address

Shipping address for the credit note.

billing_address

optional, billing_address

Billing address for the credit note.

einvoice

optional, einvoice

site_details_at_creation

optional, site_details_at_creation

It contains site-specific information, including timezone and organisational address.

Try in API Explorer

Creates a credit note for the specified invoice.

Impacts

Invoice

If the credit note type is adjustment:
- The adjustment credit note details are added to the adjustment_credit_notes[] attribute of the invoice.
- The invoice amount_due is reduced by the credit note total.
- The invoice status is updated to paid if the invoice amount_due equals the credit note total.
- The invoice status does not change if the invoice amount_due is greater than credit note total.
If the credit note type is refundable:
- The refundable credit note details are added to the issued_credit_notes[] attribute of the invoice.
- The invoice status does not change.
If the credit note type is store:
- The store credit note details are added to the issued_credit_notes[] attribute of the invoice.
- The invoice status does not change.

Credit note

A new credit note of the specified type is created.
If the credit note type is adjustment:
- total and amount_allocated are set to the adjusted amount.
- status is set to adjusted.
If the credit note type is refundable or store:
- total and amount_available are set to the refundable amount.
- status is set to refund_due.
The taxes[].amount and line_item_taxes[].tax_amount are set to the corresponding values on the invoice, prorated by the ratio of credit_note.total to invoice.total.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/credit_notes \
     -u {site_api_key}:\
     -d reference_invoice_id="__demo_inv__1" \
     -d total=500 \
     -d type="REFUNDABLE" \
     -d reason_code="PRODUCT_UNSATISFACTORY" \
     -d customer_notes="Products were returned because they were defective"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "credit_note": {
        "allocations": [],
        "amount_allocated": 0,
        "amount_available": 500,
        "amount_refunded": 0,
        "base_currency_code": "USD",
        "create_reason_code": "Product Unsatisfactory",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWSy4m5e",
        "date": 1517501405,
        "deleted": false,
        "exchange_rate": 1,
        "fractional_correction": 0,
        "id": "__demo_cn__1",
        "line_item_discounts": [],
        "line_item_taxes": [],
        "line_items": [
            {
                "amount": 500,
                "customer_id": "__test__KyVnHhSBWSy4m5e",
                "date_from": 1517501405,
                "date_to": 1517501405,
                "description": "Support Charge",
                "discount_amount": 0,
                "entity_type": "adhoc",
                "id": "li___test__KyVnHhSBWSyHE5r",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "flat_fee",
                "quantity": 1,
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 500
            },
            {..}
        ],
        "linked_refunds": [],
        "object": "credit_note",
        "price_type": "tax_exclusive",
        "reason_code": "product_unsatisfactory",
        "reference_invoice_id": "__demo_inv__1",
        "resource_version": 1517501405000,
        "round_off_amount": 0,
        "status": "refund_due",
        "sub_total": 500,
        "taxes": [],
        "total": 500,
        "type": "refundable",
        "updated_at": 1517501405
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 1000,
        "amount_to_collect": 0,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "Duncan",
            "last_name": "Walpole",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWSy4m5e",
        "date": 1517501404,
        "deleted": false,
        "due_date": 1517501404,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": true,
        "has_advance_charges": false,
        "id": "__demo_inv__1",
        "is_gifted": false,
        "issued_credit_notes": [
            {
                "cn_create_reason_code": "Product Unsatisfactory",
                "cn_date": 1517501405,
                "cn_id": "__demo_cn__1",
                "cn_reason_code": "product_unsatisfactory",
                "cn_status": "refund_due",
                "cn_total": 500
            },
            {..}
        ],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__KyVnHhSBWSy4m5e",
                "date_from": 1517501404,
                "date_to": 1517501404,
                "description": "Support Charge",
                "discount_amount": 0,
                "entity_type": "adhoc",
                "id": "li___test__KyVnHhSBWSy9k5l",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "flat_fee",
                "quantity": 1,
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 1000,
                "applied_at": 1517501404,
                "txn_amount": 1000,
                "txn_date": 1517501404,
                "txn_id": "txn___test__KyVnHhSBWSyEh5m",
                "txn_status": "success"
            },
            {..}
        ],
        "net_term_days": 0,
        "new_sales_amount": 1000,
        "object": "invoice",
        "paid_at": 1517501404,
        "price_type": "tax_exclusive",
        "recurring": false,
        "resource_version": 1517501405000,
        "round_off_amount": 0,
        "status": "paid",
        "sub_total": 1000,
        "tax": 0,
        "term_finalized": true,
        "total": 1000,
        "updated_at": 1517501405,
        "write_off_amount": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/credit_notes

reference_invoice_id[]

optional, string, max chars=50

The identifier of the invoice against which this credit note is issued.

Required when

type is adjustment or store.

Note When not provided and type is refundable, then customer_id must be provided because this creates a standalone credit note.

customer_id[]

optional, string, max chars=50

The identifier of the customer for whom this credit note is issued.

Required when

type is refundable and reference_invoice_id is not provided. This creates a standalone credit note.

total[]

optional, in cents, default=0, min=0

The total credit note amount.

Constraints

Pass either the total or line_items parameter.
If type is adjustment, total must not exceed the amount due on the invoice minus the total amount of any transactions in progress for the invoice. Calculate this as invoice.amount_due minus the sum of invoice.linked_payments[i].amount where invoice.linked_payments[i].txn_status is in_progress.
If type is refundable or store:
- If reference_invoice_id is provided, total must not exceed the refundable amount on the invoice. Calculate the refundable amount as the sum of:
  - Sum of linked_payments[i].amount where linked_payments[i].txn_status is success
  - Sum of applied_credits[i].applied_amount where applied_credits[i].status is not voided
  - Sum of linked_taxes_withheld[].amount
  - Minus the sum of issued_credit_notes[i].cn_total where issued_credit_notes[i].status is not voided
- If reference_invoice_id is not provided, there is no limit on the total because this creates a standalone credit note.

type[]

required, enumerated string

The type of credit note to create.

Prerequisites

If type is adjustment, the invoice.status must be payment_due, posted or not_paid.
If type is refundable or store, the invoice.status must be paid, payment_due, posted, or not_paid.

Possible values are

reason_code[]

optional, enumerated string

The reason for issuing this Credit Note. The following reason codes are supported now[Deprecated; use the create_reason_code parameter instead].

Possible values are

create_reason_code[]

optional, string, max chars=100

Reason code for creating the credit note.

Constraints

Must be one of the case-sensitive reason codes set in Chargebee Billing.

Required when

Reason codes are configured as mandatory on the site.

date[]

optional, timestamp(UTC) in seconds

The date on which the credit note is issued.

Constraints

Must be on or after the invoice.date and cannot be a future date.

customer_notes[]

optional, string, max chars=2000

A note to be added for this operation, to the credit note. This note is displayed on customer-facing documents such as the Credit Note PDF .

currency_code[]

required if Multicurrency is enabled, string, max chars=3

comment[]

optional, string, max chars=300

An internal comment to be added for this operation, to the credit note. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing Hosted Page or any document such as the Credit Note PDF .

line_items

Parameters for line_items. Multiple line_items can be passed by specifying unique indices.
pass parameters as line_items[<param name>][<idx:0..n>]

line_items[reference_line_item_id][0..n]

optional, string, max chars=40

line_items[unit_amount][0..n]

optional, in cents

line_items[unit_amount_in_decimal][0..n]

optional, string, max chars=39

line_items[quantity][0..n]

optional, integer, default=1

line_items[quantity_in_decimal][0..n]

optional, string, max chars=33

line_items[amount][0..n]

optional, in cents

line_items[date_from][0..n]

optional, timestamp(UTC) in seconds

line_items[date_to][0..n]

optional, timestamp(UTC) in seconds

line_items[description][0..n]

optional, string, max chars=250

line_items[entity_type][0..n]

optional, enumerated string

Possible values are

line_items[entity_id][0..n]

optional, string, max chars=100

credit_note

always returned
Resource object representing credit_note

invoice

optional
Resource object representing invoice

Try in API Explorer

Retrieves the Credit Note identified by the specified Credit Note number.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__7 \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "credit_note": {
        "allocations": [],
        "amount_allocated": 0,
        "amount_available": 500,
        "amount_refunded": 0,
        "base_currency_code": "USD",
        "create_reason_code": "Product Unsatisfactory",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWT0XH7a",
        "date": 1517501414,
        "deleted": false,
        "exchange_rate": 1,
        "fractional_correction": 0,
        "id": "__demo_cn__7",
        "line_item_discounts": [],
        "line_item_taxes": [],
        "line_items": [
            {
                "amount": 500,
                "customer_id": "__test__KyVnHhSBWT0XH7a",
                "date_from": 1517501414,
                "date_to": 1517501414,
                "description": "Support Charge",
                "discount_amount": 0,
                "entity_type": "adhoc",
                "id": "li___test__KyVnHhSBWT0c77n",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "flat_fee",
                "quantity": 1,
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 500
            },
            {..}
        ],
        "linked_refunds": [],
        "object": "credit_note",
        "price_type": "tax_exclusive",
        "reason_code": "product_unsatisfactory",
        "reference_invoice_id": "__demo_inv__7",
        "resource_version": 1517501414000,
        "round_off_amount": 0,
        "status": "refund_due",
        "sub_total": 500,
        "taxes": [],
        "total": 500,
        "type": "refundable",
        "updated_at": 1517501414
    }
}

URL Format GET

https://{site}.chargebee.com/api/v2/credit_notes/{credit-note-id}

line_items_limit[]

optional, integer, default=100, min=1, max=300

Specify the maximum number of line items to include in the response.

Note:

Applicable only when Enterprise-scale Invoicing is enabled.
Enterprise-scale Invoicing is currently in Private Beta. Please reach out to Chargebee Support to enable this feature.

line_items_offset[]

optional, string, max chars=1000

Specify the starting point for retrieving line items. Use the value from the line_items_next_offset attribute of the previous retrieve API response.

Note:

Applicable only when Enterprise-scale Invoicing is enabled.
Enterprise-scale Invoicing is currently in Private Beta. Please reach out to Chargebee Support to enable this feature.

credit_note

always returned
Resource object representing credit_note

Sample admin console URL

https://{site}.chargebee.com/admin-console/credit_notes/123x

Try in API Explorer

Gets the credit note as PDF. The returned URL is secure and allows download. The URL will expire in 60 minutes.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__4/pdf \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "download": {
        "download_url": "https://cb-local-downloads.s3.amazonaws.com/yourapp/credit_note/__test__KyVnHhSBWSzKF6n.pdf?response-content-disposition=attachment%3Bfilename%3Dyourapp%2Fcredit_note%2F__test__KyVnHhSBWSzKF6n.pdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20200924T161012Z&X-Amz-SignedHeaders=host&X-Amz-Expires=59&X-Amz-Credential=AKIAJI4SN7ONHAOGLOGA%2F20200924%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=e4aae0313d24d0b5bd73d4292711dd15f94811f0e7a28a271fc92ce3606037ff",
        "object": "download",
        "valid_till": 1600963872
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/credit_notes/{credit-note-id}/pdf

disposition_type[]

optional, enumerated string, default=attachment

Determines the pdf should be rendered as inline or attachment in the browser.

Possible values are

download

always returned
Resource object representing download

Try in API Explorer

Download the e-invoice for the credit note in both XML and PDF formats. The response consists of a download object for each format. The XML format follows the structure as per Peppol BIS Billing v3.0.

Note

You can only download e-invoices when their status is success or registered.
There are some cases in which the PDF is not available for download. In such cases, you can obtain it from the XML by decoding the value for cbc:EmbeddedDocumentBinaryObject, which is the Base64-encoded version of the PDF.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__1/download_einvoice \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "downloads": [
        {
            "download_url": "https://dj-temp.s3.eu-west-1.amazonaws.com/596b46e3f21011b29678bc15f5c938075755c163ae4fdb15b98f3e8e5ca6eab7cf16afc6c788b29f91e6362a7aae4867ba4153eef2838556ee541ba85af09369?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAI5G5MTYS7SBP4ZEQ%2F20211123%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20211123T070845Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=4d99603c2f7bcdd6cf450a27372ee2f95003afb64a0188b4ebe142a403e14acf",
            "mime_type": "application/xml",
            "object": "download",
            "valid_till": 1638236325
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v2/credit_notes/{credit-note-id}/download_einvoice

downloads

always returned
Resource object representing downloads

Try in API Explorer

Refunds a specified amount from a refundable credit note back to the customer's payment source.

This operation supports only refunds against online payments. The refund amount is returned to the customer through the payment_source associated with the transaction. If multiple transactions are associated with the credit note, call this API once for each transaction.

To record offline refunds, including those for linked_taxes_withheld, use the Record refund for a credit note API.

Prerequisites & Constraints

The credit note type is refundable.
The credit note status is refund_due.
The credit note has an amount_available greater than 0.
Part or all of the credit note's amount_available is from online payments.
The credit note is not standalone; it has an associated invoice.
You can process partial refunds only if the associated payment gateway supports partial refund operations.

Impacts

Credit note

The credit note's amount_available is reduced by the refunded amount.
The credit note's status is updated to refunded if the refunded amount is equal to the credit note's amount_available.
The credit note's linked_refunds is updated with the details of the refund transaction.

Transaction

Chargebee creates a transaction of type refund and links it to the credit note under credit_note.linked_refunds.

Implementation Notes

Before you call this API, make sure the following conditions are met:

The credit note type is refundable.
The credit note status is refund_due.
The credit note has an amount_available greater than 0.
The credit note has the reference_invoice_id set.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__6/refund \
     -u {site_api_key}:\
     -d customer_notes="Refunding as customer canceled the order." \
     -d refund_amount=1000

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "credit_note": {
        "allocations": [],
        "amount_allocated": 0,
        "amount_available": 0,
        "amount_refunded": 1000,
        "base_currency_code": "USD",
        "create_reason_code": "Product Unsatisfactory",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWT0N17C",
        "date": 1517501413,
        "deleted": false,
        "exchange_rate": 1,
        "fractional_correction": 0,
        "id": "__demo_cn__6",
        "line_item_discounts": [],
        "line_item_taxes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__KyVnHhSBWT0N17C",
                "date_from": 1517501413,
                "date_to": 1517501413,
                "description": "Support Charge",
                "discount_amount": 0,
                "entity_type": "adhoc",
                "id": "li___test__KyVnHhSBWT0Rm7P",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "flat_fee",
                "quantity": 1,
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_refunds": [
            {
                "applied_amount": 1000,
                "applied_at": 1517501413,
                "txn_amount": 1000,
                "txn_date": 1517501413,
                "txn_id": "txn___test__KyVnHhSBWT0Tk7T",
                "txn_status": "success"
            },
            {..}
        ],
        "object": "credit_note",
        "price_type": "tax_exclusive",
        "reason_code": "product_unsatisfactory",
        "reference_invoice_id": "__demo_inv__6",
        "refunded_at": 1517501413,
        "resource_version": 1517501413000,
        "round_off_amount": 0,
        "status": "refunded",
        "sub_total": 1000,
        "taxes": [],
        "total": 1000,
        "type": "refundable",
        "updated_at": 1517501413
    },
    "transaction": {
        "amount": 1000,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWT0N17C",
        "date": 1517501413,
        "deleted": false,
        "exchange_rate": 1,
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVnGlSBWSxm7Jj",
        "id": "txn___test__KyVnHhSBWT0Tk7T",
        "id_at_gateway": "cb___test__KyVnHhSBWT0Q57L",
        "linked_credit_notes": [
            {
                "applied_amount": 1000,
                "applied_at": 1517501413,
                "cn_create_reason_code": "Product Unsatisfactory",
                "cn_date": 1517501413,
                "cn_id": "__demo_cn__6",
                "cn_reason_code": "product_unsatisfactory",
                "cn_reference_invoice_id": "__demo_inv__6",
                "cn_status": "refunded",
                "cn_total": 1000
            },
            {..}
        ],
        "masked_card_number": "************1111",
        "object": "transaction",
        "payment_method": "card",
        "payment_source_id": "pm___test__KyVnHhSBWT0Ni7E",
        "refunded_txn_id": "txn___test__KyVnHhSBWT0Py7K",
        "resource_version": 1517501413000,
        "status": "success",
        "type": "refund",
        "updated_at": 1517501413
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/credit_notes/{credit-note-id}/refund

refund_amount[]

optional, in cents, min=1

The amount to be refunded.

Constraints

If multiple transactions are associated with the credit note, the refund can be processed only for one transaction at a time.
Offline refunds, including those for linked_taxes_withheld, cannot be refunded via this operation. Use the Record refund for a credit note API instead.

Default behavior

If not specified, the amount_available for this credit note is implied.

customer_notes[]

optional, string, max chars=2000

A note to be added for this operation, to the credit note. This note is displayed on customer-facing documents such as the Credit Note PDF .

refund_reason_code[]

optional, string, max chars=100

Reason code for the refund. Must be one from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Credit Notes > Refund Credit Note. Must be passed if set as mandatory in the app. The codes are case-sensitive.

credit_note

always returned
Resource object representing credit_note

transaction

always returned
Resource object representing transaction

Try in API Explorer

Records a refund for a refundable credit note.

This API does not process an actual refund for online payments by returning money to customers.

Use this API to record refunds processed outside Chargebee (for example, directly through a payment gateway or via offline methods such as bank transfers or checks) so you can reconcile them in Chargebee.

To process refunds via Chargebee for online payments and automatically return money to customers, use the Refund a credit note API instead.

Prerequisites & Constraints

The credit note type must be refundable.
The credit note status must be refund_due.

Impacts

Transactions

Chargebee records the refunds by creating transactions of type refund and links them to the credit note. The refund transactions are recorded in the following order:

linked_payments of the invoice associated with the credit note. This is recorded as linked_refunds[] in the credit note.
linked_taxes_withheld (if available). This is recorded as linked_tax_withheld_refunds[] in the credit note.

Implementation Notes

Before using this API, ensure:

The credit note type is refundable.
The credit note status is refund_due.
If reason codes are mandatory in Chargebee Billing, include the refund_reason_code parameter with a value from the configured list of codes.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__5/record_refund \
     -u {site_api_key}:\
     -d comment="Refunding as customer canceled the order." \
     -d "transaction[amount]"=100 \
     -d "transaction[payment_method]"="BANK_TRANSFER" \
     -d "transaction[date]"=1517501412

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "credit_note": {
        "allocations": [],
        "amount_allocated": 0,
        "amount_available": 400,
        "amount_refunded": 100,
        "base_currency_code": "USD",
        "create_reason_code": "Product Unsatisfactory",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWT0B66o",
        "date": 1517501412,
        "deleted": false,
        "exchange_rate": 1,
        "fractional_correction": 0,
        "id": "__demo_cn__5",
        "line_item_discounts": [],
        "line_item_taxes": [],
        "line_items": [
            {
                "amount": 500,
                "customer_id": "__test__KyVnHhSBWT0B66o",
                "date_from": 1517501412,
                "date_to": 1517501412,
                "description": "Support Charge",
                "discount_amount": 0,
                "entity_type": "adhoc",
                "id": "li___test__KyVnHhSBWT0IE71",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "flat_fee",
                "quantity": 1,
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 500
            },
            {..}
        ],
        "linked_refunds": [
            {
                "applied_amount": 100,
                "applied_at": 1517501412,
                "txn_amount": 100,
                "txn_date": 1517501412,
                "txn_id": "txn___test__KyVnHhSBWT0Jm75",
                "txn_status": "success"
            },
            {..}
        ],
        "object": "credit_note",
        "price_type": "tax_exclusive",
        "reason_code": "product_unsatisfactory",
        "reference_invoice_id": "__demo_inv__5",
        "resource_version": 1517501413000,
        "round_off_amount": 0,
        "status": "refund_due",
        "sub_total": 500,
        "taxes": [],
        "total": 500,
        "type": "refundable",
        "updated_at": 1517501413
    },
    "transaction": {
        "amount": 100,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWT0B66o",
        "date": 1517501412,
        "deleted": false,
        "exchange_rate": 1,
        "gateway": "not_applicable",
        "id": "txn___test__KyVnHhSBWT0Jm75",
        "linked_credit_notes": [
            {
                "applied_amount": 100,
                "applied_at": 1517501412,
                "cn_create_reason_code": "Product Unsatisfactory",
                "cn_date": 1517501412,
                "cn_id": "__demo_cn__5",
                "cn_reason_code": "product_unsatisfactory",
                "cn_reference_invoice_id": "__demo_inv__5",
                "cn_status": "refund_due",
                "cn_total": 500
            },
            {..}
        ],
        "object": "transaction",
        "payment_method": "bank_transfer",
        "resource_version": 1517501413000,
        "status": "success",
        "type": "refund",
        "updated_at": 1517501413
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/credit_notes/{credit-note-id}/record_refund

refund_reason_code[]

optional, string, max chars=100

comment[]

optional, string, max chars=300

Remarks, if any, on the refund.

transaction

Parameters for transaction
pass parameters as transaction[<param name>]

transaction[id]

optional, string, max chars=40

transaction[amount]

optional, in cents, min=0

transaction[payment_method]

required, enumerated string

Possible values are

transaction[reference_number]

optional, string, max chars=100

transaction[custom_payment_method_id]

optional, string, max chars=50

transaction[date]

required, timestamp(UTC) in seconds

credit_note

always returned
Resource object representing credit_note

transaction

optional
Resource object representing transaction

Try in API Explorer

Void or invalidate the specified credit note.

Use this operation for incorrectly generated credit notes, such as those with wrong details or created by mistake. This is a preferred method over deleting the credit note, as it preserves the audit trail, allowing for future reference and compliance without removing the original record.

Prerequisites & Constraints

The credit note status must not be refunded or voided.
For credit notes of type refundable, you must remove any allocations or linked refunds before voiding it. Note that only offline refunds can be removed; online refunds cannot.

See Implementation Notes for more details.

Impacts

Invoices

If the credit note type is adjustment, the associated invoice status changes to not_paid, and the amount_due on the invoice increases by the amount that was allocated via the credit note.

Implementation Notes

Before calling this API, ensure the following:

The credit note status must not be refunded or voided.
For credit notes of type refundable:
- Remove any allocations of the credit note to invoices by calling the Remove credit note from an invoice API.
- Remove any linked offline refunds by calling the Delete an offline transaction API.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__8/void \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "credit_note": {
        "allocations": [],
        "amount_allocated": 0,
        "amount_available": 500,
        "amount_refunded": 0,
        "base_currency_code": "USD",
        "create_reason_code": "Product Unsatisfactory",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWT0fn7r",
        "date": 1517501414,
        "deleted": false,
        "exchange_rate": 1,
        "fractional_correction": 0,
        "id": "__demo_cn__8",
        "line_item_discounts": [],
        "line_item_taxes": [],
        "line_items": [
            {
                "amount": 500,
                "customer_id": "__test__KyVnHhSBWT0fn7r",
                "date_from": 1517501414,
                "date_to": 1517501414,
                "description": "Support Charge",
                "discount_amount": 0,
                "entity_type": "adhoc",
                "id": "li___test__KyVnHhSBWT0kV84",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "flat_fee",
                "quantity": 1,
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 500
            },
            {..}
        ],
        "linked_refunds": [],
        "object": "credit_note",
        "price_type": "tax_exclusive",
        "reason_code": "product_unsatisfactory",
        "reference_invoice_id": "__demo_inv__8",
        "resource_version": 1517501414000,
        "round_off_amount": 0,
        "status": "voided",
        "sub_total": 500,
        "taxes": [],
        "total": 500,
        "type": "refundable",
        "updated_at": 1517501414,
        "voided_at": 1517501414
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 1000,
        "amount_to_collect": 0,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "Duncan",
            "last_name": "Walpole",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWT0fn7r",
        "date": 1517501414,
        "deleted": false,
        "due_date": 1517501414,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": true,
        "has_advance_charges": false,
        "id": "__demo_inv__8",
        "is_gifted": false,
        "issued_credit_notes": [
            {
                "cn_create_reason_code": "Product Unsatisfactory",
                "cn_date": 1517501414,
                "cn_id": "__demo_cn__8",
                "cn_reason_code": "product_unsatisfactory",
                "cn_status": "voided",
                "cn_total": 500
            },
            {..}
        ],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__KyVnHhSBWT0fn7r",
                "date_from": 1517501414,
                "date_to": 1517501414,
                "description": "Support Charge",
                "discount_amount": 0,
                "entity_type": "adhoc",
                "id": "li___test__KyVnHhSBWT0iC7y",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "flat_fee",
                "quantity": 1,
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 1000,
                "applied_at": 1517501414,
                "txn_amount": 1000,
                "txn_date": 1517501414,
                "txn_id": "txn___test__KyVnHhSBWT0ir7z",
                "txn_status": "success"
            },
            {..}
        ],
        "net_term_days": 0,
        "new_sales_amount": 1000,
        "object": "invoice",
        "paid_at": 1517501414,
        "price_type": "tax_exclusive",
        "recurring": false,
        "resource_version": 1517501414000,
        "round_off_amount": 0,
        "status": "paid",
        "sub_total": 1000,
        "tax": 0,
        "term_finalized": true,
        "total": 1000,
        "updated_at": 1517501414,
        "write_off_amount": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/credit_notes/{credit-note-id}/void

comment[]

optional, string, max chars=300

Reason for deleting this transaction. This comment will be added to the associated entity.

credit_note

always returned
Resource object representing credit_note

Try in API Explorer

Lists all the Credit Notes.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/credit_notes \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3 \
     --data-urlencode "type[is]"="refundable" \
     --data-urlencode "sort_by[asc]"=date

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "list": [
        {
            "credit_note": {
                "allocations": [],
                "amount_allocated": 0,
                "amount_available": 500,
                "amount_refunded": 0,
                "base_currency_code": "USD",
                "create_reason_code": "Product Unsatisfactory",
                "currency_code": "USD",
                "customer_id": "__test__KyVnHhSBWSy4m5e",
                "date": 1517501405,
                "deleted": false,
                "exchange_rate": 1,
                "fractional_correction": 0,
                "id": "__demo_cn__1",
                "line_item_discounts": [],
                "line_item_taxes": [],
                "line_items": [
                    {
                        "amount": 500,
                        "customer_id": "__test__KyVnHhSBWSy4m5e",
                        "date_from": 1517501405,
                        "date_to": 1517501405,
                        "description": "Support Charge",
                        "discount_amount": 0,
                        "entity_type": "adhoc",
                        "id": "li___test__KyVnHhSBWSyHE5r",
                        "is_taxed": false,
                        "item_level_discount_amount": 0,
                        "object": "line_item",
                        "pricing_model": "flat_fee",
                        "quantity": 1,
                        "tax_amount": 0,
                        "tax_exempt_reason": "tax_not_configured",
                        "unit_amount": 500
                    },
                    {..}
                ],
                "linked_refunds": [],
                "object": "credit_note",
                "price_type": "tax_exclusive",
                "reason_code": "product_unsatisfactory",
                "reference_invoice_id": "__demo_inv__1",
                "resource_version": 1517501405000,
                "round_off_amount": 0,
                "status": "refund_due",
                "sub_total": 500,
                "taxes": [],
                "total": 500,
                "type": "refundable",
                "updated_at": 1517501405
            }
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v2/credit_notes

limit[]

optional, integer, default=10, min=1, max=100
The number of resources to be returned.

offset[]

optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set 'offset' to the value of 'next_offset' obtained in the previous iteration of the API call.

include_deleted[]

optional, boolean, default=false

If set to true, includes the deleted resources in the response. For the deleted resources in the response, the 'deleted ' attribute will be 'true '.

sort_by[<sort-order>]

optional, string filter
Sorts based on the specified attribute.
Supported attributes : date
Supported sort-orders : asc, desc

Example → sort_by[asc] = "date"
This will sort the result based on the 'date' attribute in ascending(earliest first) order.

Filter Params

For operator usages, see the Pagination and Filtering section.

id[<operator>]

optional, string filter

Credit-note id. Supported operators : is, is_not, starts_with, in, not_in

Example → id[is] = "CN_123"

Supported operators : is, is_not, starts_with, in, not_in

Example → id[is] = "CN_123"

customer_id[<operator>]

optional, string filter

The identifier of the customer this Credit Note belongs to. Supported operators : is, is_not, starts_with, in, not_in

Example → customer_id[is] = "4gmiXbsjdm"

Supported operators : is, is_not, starts_with, in, not_in

Example → customer_id[is] = "4gmiXbsjdm"

subscription_id[<operator>]

optional, string filter

To filter based on subscription_id. NOTE: Not to be used if consolidated invoicing feature is enabled. Supported operators : is, is_not, starts_with, is_present, in, not_in

Example → subscription_id[is] = "4gmiXbsjdm"

Supported operators : is, is_not, starts_with, is_present, in, not_in

Example → subscription_id[is] = "4gmiXbsjdm"

reference_invoice_id[<operator>]

optional, string filter

The identifier of the invoice against which this Credit Note is issued. Supported operators : is, is_not, starts_with, in, not_in

Example → reference_invoice_id[is] = "INVOICE_876"

Supported operators : is, is_not, starts_with, is_present, in, not_in

Example → reference_invoice_id[is] = "INVOICE_876"

type[<operator>]

optional, enumerated string filter

The credit note type. Possible values are : adjustment, refundable, store
Supported operators : is, is_not, in, not_in

Example → type[is] = "adjustment"

reason_code[<operator>]

optional, enumerated string filter

The reason for issuing this Credit Note. The following reason codes are supported now[Deprecated; use the create_reason_code parameter instead]. Possible values are : write_off, subscription_change, subscription_cancellation, subscription_pause, chargeback, product_unsatisfactory, service_unsatisfactory, order_change, order_cancellation, waiver, other, fraudulent
Supported operators : is, is_not, in, not_in

Example → reason_code[is] = "waiver"

create_reason_code[<operator>]

optional, string filter

Example → create_reason_code[is] = "Other"

Supported operators : is, is_not, starts_with, in, not_in

Example → create_reason_code[is] = "Other"

status[<operator>]

optional, enumerated string filter

The credit note status. Possible values are : adjusted, refunded, refund_due, voided
Supported operators : is, is_not, in, not_in

Example → status[is] = "adjusted"

date[<operator>]

optional, timestamp(UTC) in seconds filter

The date the Credit Note is issued. Supported operators : after, before, on, between

Example → date[on] = "1435054328"

Supported operators : after, before, on, between

Example → date[after] = "1435054328"

total[<operator>]

optional, number filter

Credit Note amount in cents. Supported operators : is, is_not, lt, lte, gt, gte, between

Example → total[is] = "1200"

Supported operators : is, is_not, lt, lte, gt, gte, between

Example → total[is] = "1200"

price_type[<operator>]

optional, enumerated string filter

The price type of the Credit Note. Possible values are : tax_exclusive, tax_inclusive
Supported operators : is, is_not, in, not_in

Example → price_type[is] = "tax_exclusive"

amount_allocated[<operator>]

optional, number filter

The amount allocated to the invoices. Supported operators : is, is_not, lt, lte, gt, gte, between

Example → amount_allocated[is] = "1200"

Supported operators : is, is_not, lt, lte, gt, gte, between

Example → amount_allocated[is] = "1200"

amount_refunded[<operator>]

optional, number filter

The refunds issued from this Credit Note. Supported operators : is, is_not, lt, lte, gt, gte, between

Example → amount_refunded[lte] = "130"

Supported operators : is, is_not, lt, lte, gt, gte, between

Example → amount_refunded[is] = "130"

amount_available[<operator>]

optional, number filter

The yet to be used credits of this Credit Note. Supported operators : is, is_not, lt, lte, gt, gte, between

Example → amount_available[gt] = "1400"

Supported operators : is, is_not, lt, lte, gt, gte, between

Example → amount_available[is] = "1400"

voided_at[<operator>]

optional, timestamp(UTC) in seconds filter

Timestamp indicating the date and time this Credit Note gets voided. Supported operators : after, before, on, between

Example → voided_at[before] = "1435054328"

Supported operators : after, before, on, between

Example → voided_at[after] = "1435054328"

updated_at[<operator>]

optional, timestamp(UTC) in seconds filter

To filter based on updated at. This attribute will be present only if the resource has been updated after 2016-09-28. Supported operators : after, before, on, between

Example → updated_at[on] = "1243545465"

Supported operators : after, before, on, between

Example → updated_at[after] = "1243545465"

channel[<operator>]

optional, enumerated string filter

The subscription channel this object originated from and is maintained in. Possible values are : web, app_store, play_store
Supported operators : is, is_not, in, not_in

Example → channel[is] = "APP STORE"

einvoice

Parameters for einvoice

pass parameters as einvoice[<param name>][<operator>]

einvoice[status][operator]

optional, enumerated string filter

The status of processing the e-invoice. To obtain detailed information about the current status , see message .

Possible values are : scheduled, skipped, in_progress, success, failed, registered
Supported operators : is, is_not, in, not_in

Example → einvoice[status][is] = "failed"

credit_note

always returned
Resource object representing credit_note

next_offset

optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.

Try in API Explorer

This API deletes a credit note. A credit note once deleted, is deleted permanently. You cannot delete a credit which has already been deleted or refunded. If you try to delete a refunded or deleted credit note, an error message will be displayed.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__2/delete \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "credit_note": {
        "allocations": [],
        "amount_allocated": 0,
        "amount_available": 500,
        "amount_refunded": 0,
        "base_currency_code": "USD",
        "create_reason_code": "Product Unsatisfactory",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWSyLN5v",
        "date": 1517501405,
        "deleted": false,
        "exchange_rate": 1,
        "fractional_correction": 0,
        "id": "__demo_cn__2",
        "line_item_discounts": [],
        "line_item_taxes": [],
        "line_items": [
            {
                "amount": 500,
                "customer_id": "__test__KyVnHhSBWSyLN5v",
                "date_from": 1517501405,
                "date_to": 1517501405,
                "description": "Service Charge",
                "discount_amount": 0,
                "entity_type": "adhoc",
                "id": "li___test__KyVnHhSBWSyQ668",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "flat_fee",
                "quantity": 1,
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 500
            },
            {..}
        ],
        "linked_refunds": [],
        "object": "credit_note",
        "price_type": "tax_exclusive",
        "reason_code": "product_unsatisfactory",
        "reference_invoice_id": "__demo_inv__2",
        "resource_version": 1517501405000,
        "round_off_amount": 0,
        "status": "refund_due",
        "sub_total": 500,
        "taxes": [],
        "total": 500,
        "type": "refundable",
        "updated_at": 1517501405
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/credit_notes/{credit-note-id}/delete

comment[]

optional, string, max chars=300

Reason for deleting this transaction. This comment will be added to the associated entity.

credit_note

always returned
Resource object representing credit_note

Try in API Explorer

Removes a linked_tax_withheld_refunds record from the credit_note .

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__1/remove_tax_withheld_refund \
     -u {site_api_key}:\
     -d "tax_withheld[id]"="tax_wh___test__8astRSmw2zLr24"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "credit_note": {
        "allocations": [],
        "amount_allocated": 0,
        "amount_available": 200,
        "amount_refunded": 800,
        "base_currency_code": "USD",
        "channel": "web",
        "create_reason_code": "Other",
        "currency_code": "USD",
        "customer_id": "__test__8astRSmw2z1q1j",
        "date": 1517475512,
        "deleted": false,
        "exchange_rate": 1,
        "fractional_correction": 0,
        "generated_at": 1517475512,
        "id": "__demo_cn__1",
        "line_item_discounts": [],
        "line_item_taxes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8astRSmw2z1q1j",
                "date_from": 1517475512,
                "date_to": 1517475512,
                "description": "Support Charge",
                "discount_amount": 0,
                "entity_type": "adhoc",
                "id": "li___test__8astRSmw2zMR26",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "flat_fee",
                "quantity": 1,
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_refunds": [
            {
                "applied_amount": 800,
                "applied_at": 1517475512,
                "txn_amount": 800,
                "txn_date": 1517475512,
                "txn_id": "txn___test__8astRSmw2zLp23",
                "txn_status": "success"
            },
            {..}
        ],
        "object": "credit_note",
        "price_type": "tax_exclusive",
        "reason_code": "other",
        "reference_invoice_id": "__demo_inv__1",
        "resource_version": 1517475512664,
        "round_off_amount": 0,
        "status": "refund_due",
        "sub_total": 1000,
        "taxes": [],
        "total": 1000,
        "type": "refundable",
        "updated_at": 1517475512
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/credit_notes/{credit-note-id}/remove_tax_withheld_refund

tax_withheld

Parameters for tax_withheld
pass parameters as tax_withheld[<param name>]

tax_withheld[id]

required, string, max chars=40

credit_note

always returned
Resource object representing credit_note

Try in API Explorer

Resend failed einvoice in credit notes.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__1/resend_einvoice \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "credit_note": {
        "id": "__demo_cn__1",
        "customer_id": "customer",
        "reference_invoice_id": "__demo_inv__1",
        "type": "refundable",
        "reason_code": "other",
        "status": "refund_due",
        "date": 1624442701,
        "price_type": "tax_exclusive",
        "exchange_rate": 1,
        "total": 1000,
        "amount_allocated": 0,
        "amount_refunded": 0,
        "amount_available": 1000,
        "generated_at": 1624442701,
        "updated_at": 1624442701,
        "channel": "web",
        "resource_version": 1624442701287,
        "deleted": false,
        "object": "credit_note",
        "create_reason_code": "Other",
        "currency_code": "USD",
        "round_off_amount": 0,
        "fractional_correction": 0,
        "is_digital": true,
        "base_currency_code": "USD",
        "sub_total": 840,
        "einvoice": {
            "id": "HmaT0avT2mtbTL3mR",
            "status": "scheduled",
            "message": "E-invoice sending is scheduled and not yet processed.",
            "object": "einvoice"
        },
        "line_items": [
            {
                "id": "li_B1hE1ST2y3hHT3sV",
                "date_from": 1624442701,
                "date_to": 1624442701,
                "unit_amount": 840,
                "quantity": 1,
                "amount": 840,
                "pricing_model": "flat_fee",
                "is_taxed": true,
                "tax_amount": 160,
                "tax_rate": 19,
                "object": "line_item",
                "customer_id": "customer",
                "description": "none",
                "entity_type": "adhoc",
                "metered": false,
                "discount_amount": 0,
                "item_level_discount_amount": 0
            },
            {..}
        ],
        "taxes": [
            {
                "object": "tax",
                "name": "VAT",
                "description": "VAT @ 19%",
                "amount": 160
            },
            {..}
        ],
        "line_item_taxes": [
            {
                "tax_name": "VAT",
                "tax_rate": 19,
                "tax_juris_type": "country",
                "tax_juris_name": "Germany",
                "tax_juris_code": "DE",
                "object": "line_item_tax",
                "line_item_id": "li_B1hE1ST2y3hHT3sV",
                "tax_amount": 160,
                "is_partial_tax_applied": false,
                "taxable_amount": 840,
                "is_non_compliance_tax": false
            },
            {..}
        ],
        "line_item_discounts": [],
        "linked_refunds": [],
        "allocations": []
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/credit_notes/{credit-note-id}/resend_einvoice

credit_note

always returned
Resource object representing credit_note

Try in API Explorer

This endpoint is used to send an e-invoice for invoice. To support cases like TDS and invoice edits, we need to stop auto e-invoice sending and be able to send e-invoices manually. This endpoint schedules e-invoices manually. This operation is not allowed when any of the following condition matches:

If e-invoicing is not enabled at the site and customer level.
If there is an e-invoice generated already for the invoice.
If the Use automatic e-invoicing option is selected.
If there are no generated e-invoices with the failed or skipped status.
If the invoice status is voided or pending.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__1/send_einvoice \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "credit_note": {
        "allocations": [],
        "amount_allocated": 0,
        "amount_available": 500,
        "amount_refunded": 0,
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "Duncan",
            "last_name": "Walpole",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "channel": "web",
        "create_reason_code": "Product Unsatisfactory",
        "currency_code": "USD",
        "customer_id": "__test__8astSTVO2Rag1",
        "customer_notes": "Products were returned because they were defective",
        "date": 1517504571,
        "deleted": false,
        "exchange_rate": 1,
        "fractional_correction": 0,
        "generated_at": 1517504571,
        "id": "__demo_cn__1",
        "line_item_discounts": [],
        "line_item_taxes": [],
        "einvoice": {
            "id": "HmaT0avT2mtbTL3mR",
            "status": "scheduled",
            "message": "E-invoice sending is scheduled and not yet processed.",
            "object": "einvoice"
        },
        "line_items": [
            {
                "amount": 500,
                "customer_id": "__test__8astSTVO2Rag1",
                "date_from": 1517504571,
                "date_to": 1517504571,
                "description": "Support Charge",
                "discount_amount": 0,
                "entity_type": "adhoc",
                "id": "li___test__8astSTVO2TPdG",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "flat_fee",
                "quantity": 1,
                "reference_line_item_id": "li___test__8astSTVO2SsQ9",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 500
            },
            {..}
        ],
        "linked_refunds": [],
        "object": "credit_note",
        "price_type": "tax_exclusive",
        "reason_code": "product_unsatisfactory",
        "reference_invoice_id": "__demo_inv__1",
        "resource_version": 1517504571791,
        "round_off_amount": 0,
        "status": "refund_due",
        "sub_total": 500,
        "taxes": [],
        "total": 500,
        "type": "refundable",
        "updated_at": 1517504571
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/credit_notes/{credit-note-id}/send_einvoice

credit_note

always returned
Resource object representing credit_note

Try in API Explorer

Use this api to import credit notes into your Chargebee site. Billing address, Shipping Address, Vat number will be copied from the reference invoice.

This API is not enabled for live sites by default. Please contact support to get this enabled.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/credit_notes/import_credit_note \
     -u {site_api_key}:\
     -d id="old_cn_001" \
     -d customer_id="__test__XpbBxQiS4HD1nWYL" \
     -d subscription_id="__test__XpbBxQiS4HD1nWYL" \
     -d reference_invoice_id="__demo_inv__7" \
     -d type="REFUNDABLE" \
     -d currency_code="USD" \
     -d create_reason_code="Product Unsatisfactory" \
     -d date=1517429430 \
     -d total=4900 \
     -d status="REFUND_DUE" \
     -d "line_items[date_from][0]"=1517429430 \
     -d "line_items[date_to][0]"=1519848630 \
     -d "line_items[description][0]"="Support Charge" \
     -d "line_items[unit_amount][0]"=4900 \
     -d "line_items[quantity][0]"=1 \
     -d "line_items[entity_type][0]"="PLAN_ITEM_PRICE" \
     -d "line_items[entity_id][0]"="plan1"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "credit_note": {
        "allocations": [],
        "amount_allocated": 0,
        "amount_available": 500,
        "amount_refunded": 0,
        "base_currency_code": "USD",
        "create_reason_code": "Product Unsatisfactory",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWT0XH7a",
        "date": 1517501414,
        "deleted": false,
        "exchange_rate": 1,
        "fractional_correction": 0,
        "id": "__demo_cn__7",
        "line_item_discounts": [],
        "line_item_taxes": [],
        "line_items": [
            {
                "amount": 500,
                "customer_id": "__test__KyVnHhSBWT0XH7a",
                "date_from": 1517501414,
                "date_to": 1517501414,
                "description": "Support Charge",
                "discount_amount": 0,
                "entity_type": "adhoc",
                "id": "li___test__KyVnHhSBWT0c77n",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "flat_fee",
                "quantity": 1,
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 500
            },
            {..}
        ],
        "linked_refunds": [],
        "object": "credit_note",
        "price_type": "tax_exclusive",
        "reason_code": "product_unsatisfactory",
        "reference_invoice_id": "__demo_inv__7",
        "resource_version": 1517501414000,
        "round_off_amount": 0,
        "status": "refund_due",
        "sub_total": 500,
        "taxes": [],
        "total": 500,
        "type": "refundable",
        "updated_at": 1517501414
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/credit_notes/import_credit_note

id[]

required, string, max chars=50

Credit Note Number.

customer_id[]

optional, string, max chars=50

This identifies the customer for whom the credit note needs to be created.

subscription_id[]

optional, string, max chars=50

The identifier of the subscription for which this credit note needs to be created.

reference_invoice_id[]

required, string, max chars=50

The identifier of the invoice against which this Credit Note is issued.

type[]

required, enumerated string

The credit note type. Learn more about credit note types.

Possible values are

currency_code[]

required if Multicurrency is enabled, string, max chars=3

The currency code (ISO 4217 format) for the credit note.

create_reason_code[]

required, string, max chars=100

date[]

required, timestamp(UTC) in seconds

The date the Credit Note is issued.

status[]

optional, enumerated string

The credit note status.

Possible values are

total[]

optional, in cents, default=0, min=0

Credit Note amount in cents.

refunded_at[]

optional, timestamp(UTC) in seconds

The time this Credit Note gets fully used. Please note that this field is not present when partial refunds are issued.

voided_at[]

optional, timestamp(UTC) in seconds

Timestamp indicating the date and time this Credit Note gets voided.

sub_total[]

optional, in cents, min=0

The Credit Note sub-total.

round_off_amount[]

optional, in cents, min=-99, max=99

fractional_correction[]

optional, in cents, min=-50000, max=50000

Indicates the fractional correction amount.

vat_number_prefix[]

optional, string, max chars=10

An overridden value for the first two characters of the full VAT number. Only applicable specifically for customers with billing_address

country as XI (which is United Kingdom - Northern Ireland ).

When you have enabled EU VAT in 2021 or have manually enabled the Brexit configuration, you have the option of setting billing_address

line_items

Parameters for line_items. Multiple line_items can be passed by specifying unique indices.
pass parameters as line_items[<param name>][<idx:0..n>]

line_items[reference_line_item_id][0..n]

optional, string, max chars=40

line_items[id][0..n]

optional, string, max chars=40

line_items[date_from][0..n]

optional, timestamp(UTC) in seconds

line_items[date_to][0..n]

optional, timestamp(UTC) in seconds

line_items[subscription_id][0..n]

optional, string, max chars=50

line_items[description][0..n]

required, string, max chars=250

line_items[unit_amount][0..n]

optional, in cents

line_items[quantity][0..n]

optional, integer, default=1

line_items[amount][0..n]

optional, in cents

line_items[unit_amount_in_decimal][0..n]

optional, string, max chars=39

line_items[quantity_in_decimal][0..n]

optional, string, max chars=33

line_items[amount_in_decimal][0..n]

optional, string, max chars=39

line_items[entity_type][0..n]

optional, enumerated string

Possible values are

line_items[entity_id][0..n]

optional, string, max chars=100

line_items[item_level_discount1_entity_id][0..n]

optional, string, max chars=100

line_items[item_level_discount1_amount][0..n]

optional, in cents, min=0

line_items[item_level_discount2_entity_id][0..n]

optional, string, max chars=100

line_items[item_level_discount2_amount][0..n]

optional, in cents, min=0

line_items[tax1_name][0..n]

optional, string, max chars=50

line_items[tax1_amount][0..n]

optional, in cents, min=0

line_items[tax2_name][0..n]

optional, string, max chars=50

line_items[tax2_amount][0..n]

optional, in cents, min=0

line_items[tax3_name][0..n]

optional, string, max chars=50

line_items[tax3_amount][0..n]

optional, in cents, min=0

line_items[tax4_name][0..n]

optional, string, max chars=50

line_items[tax4_amount][0..n]

optional, in cents, min=0

line_items[tax5_name][0..n]

optional, string, max chars=50

line_items[tax5_amount][0..n]

optional, in cents, min=0

line_items[tax6_name][0..n]

optional, string, max chars=50

line_items[tax6_amount][0..n]

optional, in cents, min=0

line_items[tax7_name][0..n]

optional, string, max chars=50

line_items[tax7_amount][0..n]

optional, in cents, min=0

line_items[tax8_name][0..n]

optional, string, max chars=50

line_items[tax8_amount][0..n]

optional, in cents, min=0

line_items[tax9_name][0..n]

optional, string, max chars=50

line_items[tax9_amount][0..n]

optional, in cents, min=0

line_items[tax10_name][0..n]

optional, string, max chars=50

line_items[tax10_amount][0..n]

optional, in cents, min=0

line_item_tiers

Parameters for line_item_tiers. Multiple line_item_tiers can be passed by specifying unique indices.
pass parameters as line_item_tiers[<param name>][<idx:0..n>]

line_item_tiers[line_item_id][0..n]

required, string, max chars=40

line_item_tiers[starting_unit][0..n]

optional, integer, min=0

line_item_tiers[ending_unit][0..n]

optional, integer

line_item_tiers[quantity_used][0..n]

optional, integer, min=0

line_item_tiers[unit_amount][0..n]

optional, in cents, min=0

line_item_tiers[starting_unit_in_decimal][0..n]

optional, string, max chars=33

line_item_tiers[ending_unit_in_decimal][0..n]

optional, string, max chars=33

line_item_tiers[quantity_used_in_decimal][0..n]

optional, string, max chars=33

line_item_tiers[unit_amount_in_decimal][0..n]

optional, string, max chars=40

discounts

Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]

discounts[line_item_id][0..n]

optional, string, max chars=40

discounts[entity_type][0..n]

required, enumerated string

Possible values are

discounts[entity_id][0..n]

optional, string, max chars=100

discounts[description][0..n]

optional, string, max chars=250

discounts[amount][0..n]

required, in cents, min=0

taxes

Parameters for taxes. Multiple taxes can be passed by specifying unique indices.
pass parameters as taxes[<param name>][<idx:0..n>]

taxes[name][0..n]

required, string, max chars=100

taxes[rate][0..n]

required, double, default=0.0, min=0.0, max=100.0

taxes[amount][0..n]

optional, in cents, min=0

taxes[description][0..n]

optional, string, max chars=50

taxes[juris_type][0..n]

optional, enumerated string, default=other

Possible values are

taxes[juris_name][0..n]

optional, string, max chars=250

taxes[juris_code][0..n]

optional, string, max chars=250

allocations

Parameters for allocations. Multiple allocations can be passed by specifying unique indices.
pass parameters as allocations[<param name>][<idx:0..n>]

allocations[invoice_id][0..n]

required, string, max chars=50

allocations[allocated_amount][0..n]

required, in cents, min=1

allocations[allocated_at][0..n]

required, timestamp(UTC) in seconds

linked_refunds

Parameters for linked_refunds. Multiple linked_refunds can be passed by specifying unique indices.
pass parameters as linked_refunds[<param name>][<idx:0..n>]

linked_refunds[id][0..n]

optional, string, max chars=40

linked_refunds[amount][0..n]

required, in cents, min=1

linked_refunds[payment_method][0..n]

required, enumerated string

Possible values are

linked_refunds[date][0..n]

required, timestamp(UTC) in seconds

linked_refunds[reference_number][0..n]

optional, string, min chars=1, max chars=100

credit_note

always returned
Resource object representing credit_note

Credit Note Types

Sample credit note [ JSON ]

API Index URL

Model Class

Credit note attributes

Consent Fields for Credit note

Custom Fields for Credit note

Create credit note ¶

Impacts

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve a credit note ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve credit note as PDF ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Download e-invoice for credit note ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Refund a credit note ¶

Prerequisites & Constraints

Impacts

Implementation Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Record refund for a credit note ¶

Prerequisites & Constraints

Impacts

Implementation Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Void a credit note ¶

Prerequisites & Constraints

Impacts

Implementation Notes

Related APIs

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.