Introducing the Better Auth Chargebee plugin: Use it to handle subscriptions, billing, and auth seamlessly.Try now
ChargebeechargebeeAPI

Import credit note

Idempotency Supported

Imports a credit note into Chargebee Billing. This endpoint allows you to import a credit note from external systems, such as accounting software, into Chargebee.

Use this operation during data migration or reconciliation to ensure historical credits are represented in the system. The credit note is linked to a reference invoice and can be allocated to other invoices or recorded as refunded to the customer.

Impacts

Credit Note

The credit note's billing_address, shipping_address, and vat_number are copied from the reference invoice.

Invoices

Reference invoice
Other invoices
  • If allocations[] are provided, then for each allocated invoice:
    • the invoice's amount_due decreases by the allocated amount
    • the invoice status changes to paid if the amount_due becomes zero
    • an applied credit record is created to track the allocation.

Transactions

If linked_refunds[] are provided, then for each refund provided, a transaction of type refund is created with status set to success.

Sample Request

Sample Result[JSON]

URL Format

POST https://[site].chargebee.com/api/v2/credit_notes/import_credit_note

Input Parameters

id
required, string, max chars=50

The unique identifier for the credit note (credit note number).

Constraints

  • Must not conflict with existing credit note numbers in your Chargebee Billing site.
  • Must not conflict with future credit note numbers that your Chargebee Billing site may generate.
customer_id
optional, string, max chars=50

The unique identifier of the customer for whom the credit note is created.

Required if

  • subscription_id is not provided.

Constraints

  • Must match the customer of the reference_invoice_id.
subscription_id
optional, string, max chars=50

The unique identifier of the subscription for which this credit note is created.

Required if

  • customer_id is not provided.

Constraints

  • Must match the subscription of the reference_invoice_id.
  • Must not be provided if line_items[subscription_id][] is provided.
reference_invoice_id
required, string, max chars=50

The unique identifier of the invoice against which this credit note is issued. The invoice must already exist in your Chargebee Billing site.

type
required, enumerated string

The credit note type. Determines how the credit note can be used. Learn more about credit note types.

Enum Values
adjustment

Adjustment credit note.

refundable

Refundable credit note.

store

Store credit note.

Constraints

  • The type value store is not supported for this API operation.
currency_code
required if Multicurrency is enabled, string, max chars=3

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

Required if

create_reason_code
required, string, max chars=100

The reason code for creating the credit note.

Required if

  • Reason codes are mandatory in Chargebee Billing.

Constraints

  • Must be a valid and enabled reason code from the list configured in Chargebee Billing.
  • The reason code can also be from Refund Credit Note reason codes.
  • The codes are case-sensitive.
date
required, timestamp(UTC) in seconds

The date when the credit note was issued.

Constraints

  • Must be a date in the past.
  • Must be after the date of the reference invoice.
status
optional, enumerated string

The status of the credit note. Determines the current state of the credit note and how it can be used.

Default value

  • adjusted if type is adjustment.
  • if type is refundable:
    • refunded if the credit note total is equal to the sum of linked_refunds[amount][] plus the sum of allocations[allocated_amount][].
    • refund_due otherwise.
Enum Values
adjusted

The credit note has been adjusted against an invoice.

Constraints

  • Must only be set when type is adjustment.
  • Requires allocations[] to be provided and linked_refunds[] must not be provided.
refunded

The entire credit note amount has been used (either allocated to invoices or refunded).

Constraints

  • Must only be set when type is refundable.
  • Requires linked_refunds[] and/or allocations[] to be provided.
  • The sum of linked_refunds[amount][] plus the sum of allocations[allocated_amount][] must equal the credit note total.
refund_due

The credits are yet to be used or have been partially used.

Constraints

  • Must only be set when type is refundable.
  • The credit note total must be greater than the sum of linked_refunds[amount][] plus the sum of allocations[allocated_amount][].
voided

The credit note has been cancelled.

Constraints

  • linked_refunds[] and allocations[] must not be provided when status is voided.
total
optional, in cents, default=0, min=0

The total amount of the credit note.

Constraints

  • For refundable credit notes (type = refundable), this must be less than or equal to the reference invoice's refundable amount.
  • For adjustment credit notes (type = adjustment), this must be less than or equal to the reference invoice's amount_to_collect.
refunded_at
optional, timestamp(UTC) in seconds

The timestamp when this credit note was fully used (refunded or allocated). This field is automatically set when the credit note status becomes refunded or adjusted.

voided_at
optional, timestamp(UTC) in seconds

The timestamp indicating when this credit note was voided.

Constraints

  • status must be voided.

Default value

  • The credit note date.
sub_total
optional, in cents, min=0

The credit note sub-total (total before round-off, fractional correction, and taxes).

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

The rounded-off amount for the credit note. For example, if the credit note amount is $99.99 and it is rounded off to $100.00, then $0.01 is the round_off_amount.

Constraints

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

Indicates the fractional correction amount.

vat_number_prefix
optional, string, max chars=10

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

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

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

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.

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

Returns

credit_note
Credit note object
Resource object representing credit_note