Credit notes

API Version

Product Catalog

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
}

Model Class

ChargeBee::CreditNote

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

adjustmentAdjustment Credit NoterefundableRefundable Credit NotestoreStore 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 enabledsubscription_cancellationThis reason will be set automatically for Credit Notes created during cancel subscription operationsubscription_pauseThis reason will be automatically set to credit notes created during pause/resume subscription operation.

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

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.

reference_number

optional, string, max chars=100
This attribute is used to populate the unique reference number assigned to an invoice on the Invoice Registration Portal (IRP) network. It is essential for identifying and tracking invoices that are processed through the IRP network. In the future, this field may be used to store similar reference numbers for other networks.

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.registeredThe e-invoice was sent and there was an error due to which it was not delivered but got cleared in the IRP.

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.tieredThere are quantity tiers for which per unit prices are set. Quantities are purchased from successive tiers.volumeThe per unit price is based on the tier that the total quantity falls in.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=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
Indicates whether the line item is for a metered item.If true, the item is metered; otherwise, it is non-metered.

is_percentage_pricing

optional, boolean
Indicates whether the line item is percentage-based

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

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 exempt

Show all values[+]

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

per_unitIndicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).flat_feeIndicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the stairstep pricing model, pricing_type will be set to flat_fee by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.packageIndicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20 consuming 400 units will result in a charge of $80 (4 × $20).

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.

taxes
Show attributes [+]

optional, list of tax
The tax-lines 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

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_attentionWhen connection with the Gateway gets terminated abruptly. For needs_attention status Chargebee automatically reconcile the transaction for few gateways, for rest of the gateways you have to use the Reconcile transaction API. You can use this API to update the id_at_gateway (Gateway Transaction ID) and status for a needs_attention transaction to be reconciled at par with the gateway.

Learn more about needs_attention transaction status

late_failureIndicates that a successful payment transaction has failed now due to a late failure notification from the payment gateway, typically caused by issues like insufficient funds or a closed bank account.

txn_date

optional, timestamp(UTC) in seconds
Indicates when this transaction occurred.

txn_amount

optional, in cents, min=0
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.

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.

tax_application

optional, enumerated string
Specifies how tax is handled for invoice allocations made from this credit note.

Possible values are

pre_taxAllocations are applied before tax calculation.post_taxAllocations are applied after tax calculation.

shipping_address
Show attributes [+]

optional, shipping_address
Shipping address for the quote.

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

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.

index

integer, min=0
The index number of the subscription/one-time group to which the item price is added. Provide a unique number between 0 and 9 (inclusive) for each group that is to be created. To increase this limit, contact Chargebee Support

billing_address
Show attributes [+]

optional, billing_address
Billing address for the quote.

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

state

optional, string, max chars=50
State or Province

country

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

site_details_at_creation
Show attributes [+]

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

tax_origin
Show attributes [+]

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

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

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

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

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

adjustmentAdjustment Credit NoterefundableRefundable Credit NotestoreStore 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

Show all values[+]

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

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

resource_version

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

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

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

create_reason_code

vat_number_prefix

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.

einvoice

line_items

optional, list of line_item
The line items of this Credit Note

discounts

optional, list of discount
The list of discounts applied to this Credit Note

line_item_discounts

optional, list of line_item_discount
The list of discount(s) applied for each line item of this invoice.

line_item_tiers

optional, list of line_item_tier
The list of tiers applicable for this line item

taxes

optional, list of tax
The tax-lines of this Credit Note

line_item_taxes

optional, list of line_item_tax
The list of taxes applied on line items

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

billing_address

optional, billing_address
Billing address for the quote.

site_details_at_creation

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

tax_origin

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

line_item_addresses

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

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 Codes

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.create({
  :reference_invoice_id => "__demo_inv__1",
  :total => 500,
  :type => "REFUNDABLE",
  :reason_code => "PRODUCT_UNSATISFACTORY",
  :customer_notes => "Products were returned because they were defective"
  })
credit_note = result.credit_note
invoice = result.invoice

copy

Click to Copy

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.create({
  :reference_invoice_id => "__demo_inv__1",
  :total => 500,
  :type => "REFUNDABLE",
  :reason_code => "PRODUCT_UNSATISFACTORY",
  :customer_notes => "Products were returned because they were defective"
  })
credit_note = result.credit_note
invoice = result.invoice

Sample Result [ 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
    }
}

Method

ChargeBee::CreditNote.create({<param name> => <value>,<param name> => <value> ...})

reference_invoice_id[]

optional, string, max chars=50
The identifier of the invoice against which this Credit Note is issued.

customer_id[]

optional, string, max chars=50
The unique identifier of the customer resource for which the credit note should be created. This is required when standalone credit note has to be created.

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. Learn more about credit note types.

Possible values are

adjustmentAdjustment Credit NoterefundableRefundable Credit NotestoreStore 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

create_reason_code[]

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.

currency_code[]

required if Multicurrency is enabled, string, max chars=3
The currency code (ISO 4217 format) for the credit note. It is required for standalone credit note if Multicurrency is enabled.

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

Array containing hash of parameters for line_items
pass parameters as line_items => [{"<param name>" => "<value>",...}, {..}...]

reference_line_item_id

optional, string, max chars=40
Uniquely identifies a line_item

unit_amount

optional, in cents
Unit amount of the line item. Required for FLAT_FEE, PER_UNIT and VOLUME pricing model.

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

quantity

optional, integer, default=1
Quantity of the line item. Required for PER_UNIT and VOLUME pricing model.

quantity_in_decimal

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.

amount

optional, in cents
Amount of the line item. Applicable only for STAIRSTEP, TIERED pricing_model.

date_from

optional, timestamp(UTC) in seconds
Start date of this line item.

date_to

optional, timestamp(UTC) in seconds
End date of this line item.

description

optional, string, max chars=250
Description for the line item.

entity_type

optional, enumerated string
Specifies the modelled entity this line item is based on. The entity type is required for standalone credit notes.

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.

credit_note

always returned
Resource object representing credit_note

invoice

optional
Resource object representing invoice

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

Sample Codes

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.retrieve("__demo_cn__7")
credit_note = result.credit_note

copy

Click to Copy

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.retrieve("__demo_cn__7")
credit_note = result.credit_note

Sample Result [ 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
    }
}

Method

ChargeBee::CreditNote.retrieve(<credit_note_id>,{<param name> => <value>,<param name> => <value> ...})

line_items_limit[]

optional, integer, default=100, min=1, max=300
Specify the maximum number of line items to return in the response.

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.

credit_note

always returned
Resource object representing credit_note

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

Sample Codes

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.pdf("__demo_cn__4")
download = result.download

copy

Click to Copy

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.pdf("__demo_cn__4")
download = result.download

Sample Result [ 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
    }
}

Method

ChargeBee::CreditNote.pdf(<credit_note_id>,{<param name> => <value>,<param name> => <value> ...})

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

download

always returned
Resource object representing download

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 Codes

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.download_einvoice("__demo_cn__1")
downloads = result.downloads

copy

Click to Copy

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.download_einvoice("__demo_cn__1")
downloads = result.downloads

Sample Result [ 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
        },
        {..}
    ]
}

Method

ChargeBee::CreditNote.download_einvoice(<credit_note_id>,{<param name> => <value>,<param name> => <value> ...})

downloads

always returned
Resource object representing download

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 Codes

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.refund("__demo_cn__6",{
  :customer_notes => "Refunding as customer canceled the order.",
  :refund_amount => 1000
  })
credit_note = result.credit_note
transaction = result.transaction

copy

Click to Copy

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.refund("__demo_cn__6",{
  :customer_notes => "Refunding as customer canceled the order.",
  :refund_amount => 1000
  })
credit_note = result.credit_note
transaction = result.transaction

Sample Result [ 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
    }
}

Method

ChargeBee::CreditNote.refund(<credit_note_id>,{<param name> => <value>,<param name> => <value> ...})

refund_amount[]

optional, in cents, 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[]

credit_note

always returned
Resource object representing credit_note

transaction

always returned
Resource object representing transaction

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 Codes

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.record_refund("__demo_cn__5",{
  :comment => "Refunding as customer canceled the order.",
  :transaction => {
    :amount => 100,
    :payment_method => "BANK_TRANSFER",
    :date => 1517501412
    }
  })
credit_note = result.credit_note
transaction = result.transaction

copy

Click to Copy

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.record_refund("__demo_cn__5",{
  :comment => "Refunding as customer canceled the order.",
  :transaction => {
    :amount => 100,
    :payment_method => "BANK_TRANSFER",
    :date => 1517501412
    }
  })
credit_note = result.credit_note
transaction = result.transaction

Sample Result [ 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
    }
}

Method

ChargeBee::CreditNote.record_refund(<credit_note_id>,{<param name> => <value>,<param name> => <value> ...})

refund_reason_code[]

comment[]

optional, string, max chars=300
Remarks, if any, on the refund.

transaction

Hash of parameters for transaction
pass parameters as transaction => {"<param name>" => "<value>",...}

amount

optional, in cents, min=0
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.

payment_method

required, enumerated string
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 typescustomCustom

reference_number

optional, string, max chars=100
The reference number for this transaction. For example, the check number when payment_method = check.

custom_payment_method_id

optional, string, max chars=50
Identifier of the custom payment method of this transaction.

date

required, timestamp(UTC) in seconds
Indicates when this transaction occurred.

credit_note

always returned
Resource object representing credit_note

transaction

optional
Resource object representing transaction

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 Codes

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.void_credit_note("__demo_cn__8")
credit_note = result.credit_note

copy

Click to Copy

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.void_credit_note("__demo_cn__8")
credit_note = result.credit_note

Sample Result [ 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
    }
}

Method

ChargeBee::CreditNote.void_credit_note(<credit_note_id>,{<param name> => <value>,<param name> => <value> ...})

comment[]

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

credit_note

always returned
Resource object representing credit_note

Lists all the Credit Notes.

Sample Codes

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
list = ChargeBee::CreditNote.list({
  :limit => 3,
  "type[is]" => "refundable",
  "sort_by[asc]" => "date"
  })
list.each do |entry|
  credit_note = entry.credit_note
end

copy

Click to Copy

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
list = ChargeBee::CreditNote.list({
  :limit => 3,
  "type[is]" => "refundable",
  "sort_by[asc]" => "date"
  })
list.each do |entry|
  credit_note = entry.credit_note
end

Sample Result [ 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
            }
        },
        {..}
    ]
}

Method

ChargeBee::CreditNote.list({<param name> => <value>,<param name> => <value> ...})

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, 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
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, number filter
Credit Note amount in cents.
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"

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[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[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[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[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>]" => "<value>",...}

status

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

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 Codes

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.delete("__demo_cn__2")
credit_note = result.credit_note

copy

Click to Copy

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.delete("__demo_cn__2")
credit_note = result.credit_note

Sample Result [ 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
    }
}

Method

ChargeBee::CreditNote.delete(<credit_note_id>,{<param name> => <value>,<param name> => <value> ...})

comment[]

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

credit_note

always returned
Resource object representing credit_note

Removes a linked_tax_withheld_refunds record from the credit_note.

Sample Codes

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.remove_tax_withheld_refund("__demo_cn__1",{
  :tax_withheld => {
    :id => "tax_wh___test__8astRSmw2zLr24"
    }
  })
credit_note = result.credit_note

copy

Click to Copy

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.remove_tax_withheld_refund("__demo_cn__1",{
  :tax_withheld => {
    :id => "tax_wh___test__8astRSmw2zLr24"
    }
  })
credit_note = result.credit_note

Sample Result [ 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
    }
}

Method

ChargeBee::CreditNote.remove_tax_withheld_refund(<credit_note_id>,{<param name> => <value>,<param name> => <value> ...})

tax_withheld

Hash of parameters for tax_withheld
pass parameters as tax_withheld => {"<param name>" => "<value>",...}

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.

credit_note

always returned
Resource object representing credit_note

Resend failed einvoice in credit notes.

Sample Codes

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.resend_einvoice("__demo_cn__1")
credit_note = result.credit_note

copy

Click to Copy

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.resend_einvoice("__demo_cn__1")
credit_note = result.credit_note

Sample Result [ 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": []
    }
}

Method

ChargeBee::CreditNote.resend_einvoice(<credit_note_id>,{<param name> => <value>,<param name> => <value> ...})

credit_note

always returned
Resource object representing credit_note

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 Codes

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.send_einvoice("__demo_cn__1")
credit_note = result.credit_note

copy

Click to Copy

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.send_einvoice("__demo_cn__1")
credit_note = result.credit_note

Sample Result [ 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
    }
}

Method

ChargeBee::CreditNote.send_einvoice(<credit_note_id>,{<param name> => <value>,<param name> => <value> ...})

credit_note

always returned
Resource object representing credit_note

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 Codes

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.import_credit_note({
  :id => "old_cn_001",
  :customer_id => "__test__XpbBxQiS4HD1nWYL",
  :subscription_id => "__test__XpbBxQiS4HD1nWYL",
  :reference_invoice_id => "__demo_inv__7",
  :type => "REFUNDABLE",
  :currency_code => "USD",
  :create_reason_code => "Product Unsatisfactory",
  :date => 1517429430,
  :total => 4900,
  :status => "REFUND_DUE",
  :line_items => [
    {
      :date_from => 1517429430,
      :date_to => 1519848630,
      :description => "Support Charge",
      :unit_amount => 4900,
      :quantity => 1,
      :entity_type => "PLAN_ITEM_PRICE",
      :entity_id => "plan1"
    }]
  })
credit_note = result.credit_note

copy

Click to Copy

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::CreditNote.import_credit_note({
  :id => "old_cn_001",
  :customer_id => "__test__XpbBxQiS4HD1nWYL",
  :subscription_id => "__test__XpbBxQiS4HD1nWYL",
  :reference_invoice_id => "__demo_inv__7",
  :type => "REFUNDABLE",
  :currency_code => "USD",
  :create_reason_code => "Product Unsatisfactory",
  :date => 1517429430,
  :total => 4900,
  :status => "REFUND_DUE",
  :line_items => [
    {
      :date_from => 1517429430,
      :date_to => 1519848630,
      :description => "Support Charge",
      :unit_amount => 4900,
      :quantity => 1,
      :entity_type => "PLAN_ITEM_PRICE",
      :entity_id => "plan1"
    }]
  })
credit_note = result.credit_note

Sample Result [ 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
    }
}

Method

ChargeBee::CreditNote.import_credit_note({<param name> => <value>,<param name> => <value> ...})

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

adjustmentAdjustment Credit NoterefundableRefundable Credit NotestoreStore Credit Note

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
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[]

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[]

fractional_correction[]

optional, in cents, min=-50000, max=50000
Indicates the fractional correction amount.

vat_number_prefix[]

line_items

Array containing hash of parameters for line_items
pass parameters as line_items => [{"<param name>" => "<value>",...}, {..}...]

reference_line_item_id

optional, string, max chars=40
Uniquely identifies a line_item of invoice for which this reversal represents.

id

optional, string, max chars=40
Uniquely identifies a line_item

date_from

optional, timestamp(UTC) in seconds
Start date of this line item.

date_to

optional, timestamp(UTC) in seconds
End date of this line item.

subscription_id

optional, string, max chars=50
A unique identifier for the subscription this line item belongs to.

description

required, string, max chars=250
Description for this line item

unit_amount

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

Quantity of the recurring item which is represented by this line item.

amount

optional, in cents
Total amount of this lineitem. Not required if the line_items[unit_amount] param is passed

unit_amount_in_decimal

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

entity_type

optional, enumerated string
Specifies the modelled entity this line item is based on.

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

item_level_discount1_entity_id

optional, string, max chars=100
First item level discount entity id

item_level_discount1_amount

optional, in cents, min=0
First item level discount amount

item_level_discount2_entity_id

optional, string, max chars=100
Second item level discount entity id

item_level_discount2_amount

optional, in cents, min=0
Second item level discount amount

tax1_name

optional, string, max chars=50
First tax name

tax1_amount

optional, in cents, min=0
First tax amount

tax2_name

optional, string, max chars=50
Second tax name

tax2_amount

optional, in cents, min=0
Second tax amount

tax3_name

optional, string, max chars=50
Third tax name

tax3_amount

optional, in cents, min=0
Third tax amount

tax4_name

optional, string, max chars=50
Fourth tax name

tax4_amount

optional, in cents, min=0
Fourth tax amount

tax5_name

optional, string, max chars=50
Fifth tax name

tax5_amount

optional, in cents, min=0
Fifth tax amount

tax6_name

optional, string, max chars=50
Sixth tax name

tax6_amount

optional, in cents, min=0
Sixth tax amount

tax7_name

optional, string, max chars=50
Seventh tax name

tax7_amount

optional, in cents, min=0
Seventh tax amount

tax8_name

optional, string, max chars=50
Eighth tax name

tax8_amount

optional, in cents, min=0
Eighth tax amount

tax9_name

optional, string, max chars=50
Ninth tax name

tax9_amount

optional, in cents, min=0
Ninth tax amount

tax10_name

optional, string, max chars=50
Tenth tax name

tax10_amount

optional, in cents, min=0
Tenth tax amount

line_item_tiers

Array containing hash of parameters for line_item_tiers
pass parameters as line_item_tiers => [{"<param name>" => "<value>",...}, {..}...]

line_item_id

required, string, max chars=40
Uniquely identifies a line_item

starting_unit

optional, 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

optional, integer, min=0
The number of units purchased in a range.

unit_amount

optional, 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

ending_unit_in_decimal

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

discounts

Array containing hash of parameters for discounts
pass parameters as discounts => [{"<param name>" => "<value>",...}, {..}...]

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

required, 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.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=100
When the deduction is due to a coupon, then this is the id of the coupon. Is required when discounts[entity_type] is item_level_coupon or document_level_coupon.

description

optional, string, max chars=250
Description for this deduction.

amount

required, in cents, min=0
The amount deducted. The format of this value depends on the kind of currency.

taxes

Array containing hash of parameters for taxes
pass parameters as taxes => [{"<param name>" => "<value>",...}, {..}...]

name

required, string, max chars=100
The name of the tax applied

rate

required, double, default=0.0, min=0.0, max=100.0
The rate of tax used to calculate tax amount

amount

optional, in cents, min=0
Total tax amount charged for this invoice

description

optional, string, max chars=50
Description of tax

juris_type

optional, enumerated string, default=other
The type of tax jurisdiction

Possible values are

juris_name

optional, string, max chars=250
The name of the tax jurisdiction

juris_code

optional, string, max chars=250
The tax jurisdiction code

allocations

Array containing hash of parameters for allocations
pass parameters as allocations => [{"<param name>" => "<value>",...}, {..}...]

invoice_id

required, string, max chars=50
The unique invoice ID for the allocation

allocated_amount

required, in cents, min=1
The allocated amount for the credit note

allocated_at

required, timestamp(UTC) in seconds
Time when the allocation was occurred

linked_refunds

Array containing hash of parameters for linked_refunds
pass parameters as linked_refunds => [{"<param name>" => "<value>",...}, {..}...]

amount

required, in cents, min=1
Amount of this refund transaction.

payment_method

required, enumerated string
Mode of refund.

Possible values are

cashCashcheckCheckbank_transferBank TransferotherPayment Methods other than the above typescustomCustom

date

required, timestamp(UTC) in seconds
The date of refund.

reference_number

optional, string, min chars=1, max chars=100
Reference number for this refund.

credit_note

always returned
Resource object representing credit_note

Credit Note Types

Sample credit note [ JSON ]

API Index URL GET

Model Class

Credit note attributes

Consent Fields for Credit note

Custom Fields for Credit note

Create credit note ¶

Notes

Sample Result [ 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 ¶

Notes

Sample Result [ 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 ¶

Notes

Sample Result [ 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 ¶

Notes

Sample Result [ 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 ¶

Notes

Sample Result [ 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 ¶

Notes

Sample Result [ 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 ¶

Notes

Sample Result [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List credit notes ¶

Notes