Product Catalog
    Library
You are viewing the documentation for Chargebee API V2. If you're using the older version (V1), click here.

Credit notes

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.

Chargebee supports two types of Credit Notes - Adjustment Credit Note and Refundable Credit Note.

  • Adjustment Credit Notes are created for the 'unpaid' component of the invoice and it can have statuses - Adjusted and Voided.
  • Refundable Credit Notes are created for 'paid' component of the invoice and it can have statuses - Refunded, Refund Due and Voided.

The credits available in the Refundable Credit Notes will be automatically applied when a new invoice gets generated for the customer.

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 GET

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

Credit note attributes

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
string, max chars=50
The identifier of the invoice against which this Credit Note is issued
type
enumerated string
The credit note type.
Possible values are
adjustmentAdjustment Credit Note.refundableRefundable Credit Note.
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
write_offThis reason will be set automatically for the Credit Notes created during invoice Write Off operation.subscription_changeThis reason will be set automatically for Credit Notes created during Change Subscription operation when proration is enabled.subscription_cancellationThis reason will be set automatically for Credit Notes created during cancel subscription operation.subscription_pauseThis reason will be automatically set to credit notes created during pause/resume subscription operation.
chargebackCan be set when you are recording your customer Chargebacks.product_unsatisfactoryProduct Unsatisfactory.service_unsatisfactoryService Unsatisfactory.order_changeOrder Change.order_cancellationOrder Cancellation.waiverWaiver.otherCan be set when none of the above reason codes are applicable.fraudulentFRAUDULENT.
Show all values[+]
status
enumerated string
The credit note status.
Possible values are
adjustedWhen the Credit Note has been adjusted against an invoice.refundedWhen the entire credits (Credit Note amount) have been used (i.e either allocated to invoices or refunded).refund_dueWhen the credits are yet to be used, or have been partially used.voidedWhen the Credit Note has been cancelled.
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
tax_exclusiveAll amounts in the document are exclusive of tax.tax_inclusiveAll amounts in the document are inclusive of tax.
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 the invoices.
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
webThe object was created (and is maintained) for the web channel directly in Chargebee via API or UI.app_storeThe object data is synchronized with data from in-app subscription(s) created in Apple App Store. Direct manipulation of this object via UI or API is disallowed.play_storeThe object data is synchronized with data from in-app subscription(s) created in Google Play Store. Direct manipulation of this object via UI or API is disallowed.

In-App Subscriptions is currently in early access. Contact eap@chargebee.com for more information.
.
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=0
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=0
Indicates the fractional correction amount.
deleted
boolean
Indicates that this resource has been deleted.
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
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.
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.
Einvoice attributes
id
string, max chars=50
The unique id for the e-invoice. This is auto-generated by Chargebee.
status
enumerated string
The status of processing the e-invoice. To obtain detailed information about the current status, see message.
Possible values are
scheduledSending the e-invoice to the customer has been scheduled.skippedThe e-invoice was not sent. This could be due to missing information or because the entity_identifier is not registered on the e-invoicing network.in_progressThe e-invoice has been sent and Chargebee is waiting for confirmation from the receiving entity.successThe e-invoice has been successfully delivered to the customer.failedThe e-invoice was sent and there was an error due to which it was not delivered.
message
optional, string, max chars=250
Detailed information about the status of the e-invoice. When status is skipped or failed, this contains the reason or error details. The following are some valid examples:
  • Invoice successfully sent to customer via the e-invoicing network 9090:123456
  • Invoice successfully sent to customer via email id abc@acme.com

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
flat_feeA fixed price that is not quantity-based.per_unitA fixed price per unit quantity.tieredThe per unit price is based on the tier that the total quantity falls in.volumeThere are quantity tiers for which per unit prices are set. Quantities are purchased from successive tiers.stairstepA quantity-based pricing scheme. The item is charged a fixed price based on the tier that the total quantity falls in.
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=33
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=33
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.
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
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
adhocIndicates that this lineitem is not modelled. i.e created adhoc. So the 'entity_id' attribute will be null in this caseplan_item_priceIndicates that this line item is based on plan Item Priceaddon_item_priceIndicates that this line item is based on addon Item Pricecharge_item_priceIndicates that this line item is based on charge Item Price
tax_exempt_reason
optional, enumerated string
The reason due to which the line item price/amount is exempted from tax.
Possible values are
tax_not_configuredIf tax is not enabled for the siteregion_non_taxableIf the product sold is not taxable in this region, but it is taxable in other regions, hence this region is not part of the Taxable jurisdictionexportYou are not registered for tax in the customer’s region. This is also the reason code when both billing_address and shipping_address have not been provided for the customer and subscription respectivelycustomer_exemptIf the Customer is marked as Tax exemptproduct_exemptIf the Plan or Addon is marked as Tax exemptzero_ratedIf the rate of tax is 0% and no Sales/ GST tax is collectable for that line itemreverse_chargeIf the Customer is identified as B2B customer (when VAT Number is entered), applicable for EU onlyhigh_value_physical_goodsIf physical goods are sold from outside Australia to customers in Australia, and the price of all the physical good line items is greater than AUD 1000, then tax will not be applied
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
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
item_level_couponThe deduction is due to a coupon applied to line item. The coupon id is passed as entity_id.document_level_couponThe deduction is due to a coupon applied to the invoice sub_total. The coupon id is passed as entity_id.promotional_creditsThe deduction is due to a promotional credit applied to the invoice. prorated_creditsThe deduction is due to a legacy adjustment credit applied to the invoice. The entity_id is null in this case. The legacy credits feature is superseded by adjustment_credit_notes.item_level_discountThe deduction is due to a discount applied to a line item of the invoice. The discount id is available as the entity_id. document_level_discountThe deduction is due to a discount applied to the invoice sub_total. The discount id is available as the entity_id.
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
fixed_amountwhen amount is applied as discountpercentagewhen percentage is applied as discount
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.
line_item_discounts
Show attributes[+]
optional, list of line_item_discount
The list of discount(s) applied for each line item of this invoice.
Line item discount attributes
line_item_id
string, max chars=50
The unique id of the line item that this deduction is for.
discount_type
enumerated string
The type of deduction and the amount to which it is applied.
Possible values are
item_level_couponThe deduction is due to a coupon applied to a line item of the invoice. The coupon id is available as entity_id.document_level_couponThe deduction is due to a coupon applied to the invoice sub_total. The coupon id is available as entity_id.promotional_creditsThe deduction is due to a promotional credit applied to the invoice. The entity_id is null in this case.prorated_creditsThe deduction is due to a legacy adjustment credit applied to the invoice. The entity_id is null in this case. The legacy credits feature is superseded by adjustment_credit_notes.item_level_discountThe deduction is due to a discount applied to a line item of the invoice. The discount id is available as the entity_id. document_level_discountThe deduction is due to a discount applied to the invoice sub_total. The discount id is available as the entity_id.
entity_id
optional, string, max chars=50
When the deduction is due to a coupon or a discount, then this is the id of the coupon or discount.
discount_amount
in cents, min=0
The amount deducted. The format of this value depends on the kind of currency.
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 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.
taxes
Show attributes[+]
optional, list of tax
The tax-lines of this Credit Note
Tax attributes
name
string, max chars=100
The name of the tax applied. E.g. GST.
amount
in cents, min=0
The tax amount.
description
optional, string, max chars=250
Description of the tax item.
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
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
tax_juris_type
optional, enumerated string
The type of tax jurisdiction
Possible values are
countryThe tax jurisdiction is a countryfederalThe tax jurisdiction is a federalstateThe tax jurisdiction is a statecountyThe tax jurisdiction is a countycityThe tax jurisdiction is a cityspecialSpecial tax jurisdiction.unincorporatedCombined tax of state and county.otherJurisdictions other than the ones listed above.
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.
linked_refunds
Show attributes[+]
optional, list of credit_note_transaction
Payment Refunds issued from this Credit Note
Linked refund attributes
txn_id
string, max chars=40
Uniquely identifies the transaction.
applied_amount
in cents, min=0
The transaction amount applied to this invoice
applied_at
timestamp(UTC) in seconds
Time when the transaction amount applied to this invoice.
txn_status
optional, enumerated string
The status of this transaction.
Possible values are
in_progressTransaction is being processed by the gateway. This typically happens for direct debit transactions or, in case of cards, refund transactions. Such transactions can take 2-7 days to complete, depending on the gateway and payment method.successThe transaction is successful.voidedThe transaction got voided or authorization expired at gateway.failureTransaction failed. Refer the 'error_code' and 'error_text' fields to know the reason for failuretimeoutTransaction failed because of Gateway not accepting the connection.needs_attentionConnection with Gateway got terminated abruptly. So, status of this transaction needs to be resolved manually
txn_date
optional, timestamp(UTC) in seconds
Indicates when this transaction occurred.
txn_amount
optional, in cents, min=1
Total amount of the transaction
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
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.
Linked tax withheld refund attributes
id
string, max chars=40
An auto-generated unique identifier for the tax withheld. The value starts with the prefix tax_wh_. For example, tax_wh_16BdDXSlbu4uV1Ee6.
amount
optional, in cents, min=1
The amount withheld by the customer as tax from the invoice. The unit depends on the type of currency.
description
optional, string, max chars=65k
The description for this tax withheld.
date
optional, timestamp(UTC) in seconds
Date or time associated with the tax withheld.
reference_number
optional, string, max chars=100
A unique external reference number for the tax withheld. Typically, this is the reference number used by the system you are integrating the API with. Depending on your integration, this could be the reference number issued by the taxation authority to identify the customer or the specific tax transaction.
allocations
Show attributes[+]
optional, list of applied_credit
Invoice allocations made from this Credit Note.
Allocation attributes
invoice_id
string, max chars=50
Unique identifier of the invoice.
allocated_amount
in cents, min=0
Amount of this refund transaction.
allocated_at
timestamp(UTC) in seconds
Indicates when this refund occured.
invoice_date
optional, timestamp(UTC) in seconds
Closing date of the invoice. Typically this is the date on which invoice is generated
invoice_status
enumerated string
Current status of the invoice.
Possible values are
paidIndicates a paid invoice.postedIndicates the payment is not yet collected and will be in this state till the due date to indicate the due periodpayment_dueIndicates the payment is not yet collected and is being retried as per retry settings.not_paidIndicates the payment is not made and all attempts to collect is failed.voidedIndicates a voided invoice.pending
The invoice is yet to be closed (sent for payment collection). An invoice is generated with this status when it has line items that belong to items that are metered or when the subscription.create_pending_invoicesattribute is set to true.
The invoice is yet to be closed (sent for payment collection). All invoices are generated with this status when Metered Billing is enabled for the site.

Create credit note

Creates a credit_note for the specified invoice.

Note:

If the credit_note type is refundable, then linked_taxes_withheld.amount for the invoice specified can also be included in the total.

Sample Request 
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
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"

Sample Response [ JSON ]

Show more...
{ "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

Input Parameters

reference_invoice_id
required, string, max chars=50
The identifier of the invoice against which this Credit Note is issued.
total
optional, in cents, default=0, min=0
Credit Note amount in cents. You can either pass the total parameter or the line_items parameter. Passing both will result in an error.
type
required, enumerated string
The credit note type.
Possible values are
adjustmentAdjustment Credit NoterefundableRefundable Credit Note
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
product_unsatisfactoryProduct Unsatisfactoryservice_unsatisfactoryService Unsatisfactoryorder_changeOrder Changeorder_cancellationOrder CancellationwaiverWaiverotherCan be set when none of the above reason codes are applicable
Show all values[+]
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.
date
optional, timestamp(UTC) in seconds
The date the Credit Note is issued.
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.
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]
required, string, max chars=40
Uniquely identifies a line_item
line_items[unit_amount][0..n]
optional, in cents
Unit amount of the line item. Required for FLAT_FEE, PER_UNIT and VOLUME pricing model.
line_items[unit_amount_in_decimal][0..n]
optional, string, max chars=33
The decimal representation of the unit amount of the line_item. The value is in major units of the currency. Applicable for the line_item when the pricing_model is flat_fee, per_unit or volume. Can be provided only when multi-decimal pricing is enabled.
line_items[quantity][0..n]
optional, integer, default=1
Quantity of the line item. Required for PER_UNIT and VOLUME pricing model.
line_items[quantity_in_decimal][0..n]
optional, string, max chars=33
The decimal representation of the quantity of the line_item. Applicable for the line_item when the pricing_model is per_unit and volume. Can be provided only when multi-decimal pricing is enabled.
line_items[amount][0..n]
optional, in cents
Amount of the line item. Applicable only for STAIRSTEP, TIERED pricing_model.
line_items[date_from][0..n]
optional, timestamp(UTC) in seconds
Start date of this line item.
line_items[date_to][0..n]
optional, timestamp(UTC) in seconds
End date of this line item.
line_items[description][0..n]
optional, string, max chars=250
Description for the line item.

Returns

credit_note
always returned
Resource object representing credit_note
invoice
always returned
Resource object representing invoice

Retrieve a credit note

Retrieves the Credit Note identified by the specified Credit Note number.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__7 \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__7 \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"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}

Returns

credit_note
always returned
Resource object representing credit_note

Sample admin console URL

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

Retrieve credit note as PDF

Gets the credit note as PDF. The returned URL is secure and allows download. The URL will expire in 60 minutes.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__4/pdf \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__4/pdf \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"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

Input Parameters

disposition_type
optional, enumerated string, default=attachment
Determines the pdf should be rendered as inline or attachment in the browser.
Possible values are
attachmentPDF is rendered as attachment in the browserinlinePDF is rendered as inline in the browser

Returns

download
always returned
Resource object representing download

Download e-invoice for credit note

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.
  • 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 
curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__1/download_einvoice \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__1/download_einvoice \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"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

Returns

downloads
always returned
Resource object representing download

Refund a credit note

Refunds a (refundable) credit note to the payment source associated with the transaction. Any linked_tax_withheld_refunds recorded against the credit note are not refunded.

Sample Request 
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
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

Sample Response [ JSON ]

Show more...
{ "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

Input Parameters

refund_amount
optional, integer, min=1
The amount to be refunded. If not specified, the entire refundable amount for this credit_note is refunded. Note: Any linked_tax_withheld_refunds associated with the credit_note cannot be refunded via this operation.
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.

Returns

credit_note
always returned
Resource object representing credit_note
transaction
always returned
Resource object representing transaction

Record refund for a credit note

Refunds a (refundable) credit note. The refund is provided against linked_payments first and then against any linked_taxes_withheld for the invoice associated with the credit_note. For payments made via online transactions, the refund request is processed via the payment source associated with the transaction.

Sample Request 
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
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

Sample Response [ JSON ]

Show more...
{ "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

Input Parameters

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.
comment
optional, string, max chars=300
Remarks, if any, on the refund.
+
transaction
Parameters for transaction
pass parameters as transaction[<param name>]
transaction[amount]
optional, in cents, min=1
The amount to be refunded (for online payments) or recorded as refunded (for offline payments). If not specified, the entire refundable amount for this credit_note is refunded. Note: Any linked_tax_withheld_refunds associated with the credit_note can also be recorded as refunded via this operation.
transaction[payment_method]
required, enumerated string, default=card
The payment method of this transaction
Possible values are
cashCashcheckCheckchargebackOnly applicable for a transaction of type = refund. This value is set by Chargebee when an automated chargeback occurs. You can also set this explicitly when recording a refund.
bank_transferBank TransferotherPayment Methods other than the above types
Show all values[+]
transaction[reference_number]
optional, string, max chars=100
The reference number for this transaction. For example, the check number when payment_method = check.
transaction[date]
required, timestamp(UTC) in seconds
Indicates when this transaction occurred.

Returns

credit_note
always returned
Resource object representing credit_note
transaction
optional
Resource object representing transaction

Void a credit note

Use this API to void a credit note. A voided credit is a null entity and cannot be used again. A credit note which has already been voided or refunded cannot be voided. An error message will be displayed when you render such credit notes void.

Note: When adjustment credit notes are voided, the associated invoice will reflect as NOT PAID, and the amount in the invoice will be recalculated to reflect the amount after considering the voided credit note.

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

Sample Response [ JSON ]

Show more...
{ "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

Input Parameters

comment
optional, string, max chars=300
Reason for voiding credit note. This comment will be added to the credit note.

Returns

credit_note
always returned
Resource object representing credit_note

List credit notes

Lists all the Credit Notes.

Sample Request 
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
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"

Sample Response [ JSON ]

Show more...
{"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

Input Parameters

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"
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"
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"
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"
type[<operator>]
optional, enumerated string filter
The credit note type. Possible values are : adjustment, refundable.
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
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.
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[after] = "1435054328"
total[<operator>]
optional, in cents filter
Credit Note amount in cents.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → total[lte] = "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_not] = "tax_exclusive"
amount_allocated[<operator>]
optional, in cents filter
The amount allocated to the invoices.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → amount_allocated[is_not] = "1200"
amount_refunded[<operator>]
optional, in cents filter
The refunds issued from this Credit Note.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → amount_refunded[is] = "130"
amount_available[<operator>]
optional, in cents filter
The yet to be used credits of this Credit Note.
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"
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"
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_not] = "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.
Supported operators : is, is_not, in, not_in

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

Returns

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

Delete a credit Note

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 
curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__2/delete \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__2/delete \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"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

Input Parameters

comment
optional, string, max chars=300
Reason for deleting this credit note. This comment will be added to the associated invoice entity.

Returns

credit_note
always returned
Resource object representing credit_note

Remove tax withheld refunds from a credit note

Removes a linked_tax_withheld_refunds record from the credit_note.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__1/remove_tax_withheld_refund \
     -X POST  \
     -u {site_api_key}:\
     -d tax_withheld[id]="tax_wh___test__8astRSmw2zLr24"
copy
curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__1/remove_tax_withheld_refund \
     -X POST  \
     -u {site_api_key}:\
     -d tax_withheld[id]="tax_wh___test__8astRSmw2zLr24"

Sample Response [ JSON ]

Show more...
{"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

Input Parameters

+
tax_withheld
Parameters for tax_withheld
pass parameters as tax_withheld[<param name>]
tax_withheld[id]
required, string, max chars=40
An auto-generated unique identifier for the tax withheld. The value starts with the prefix tax_wh_. For example, tax_wh_16BdDXSlbu4uV1Ee6.

Returns

credit_note
always returned
Resource object representing credit_note

Resend failed einvoice in credit notes

Resend failed einvoice in credit notes.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__1/resend_einvoice \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/credit_notes/__demo_cn__1/resend_einvoice \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"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.0, "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.0, "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.0, "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

Returns

credit_note
always returned
Resource object representing credit_note