Credit Notes
Issue a Credit Note to adjust the amount of a finalized invoice.
POST /api/v1/billing/credit_notes/createPOST /api/v1/billing/credit_notes/previewGET /api/v1/billing/credit_notes/{id}GET /api/v1/billing/credit_notesPOST /api/v1/billing/credit_notes/{id}/updatePOST /api/v1/billing/credit_notes/{id}/finalizePOST /api/v1/billing/credit_notes/{id}/deletePOST /api/v1/billing/credit_notes/{id}/voidPOST /api/v1/billing/credit_notes/{id}/add_line_itemsGET /api/v1/billing/credit_notes/{id}/line_items/{line_item_id}GET /api/v1/billing/credit_notes/{id}/line_itemsPOST /api/v1/billing/credit_notes/{id}/update_line_itemsPOST /api/v1/billing/credit_notes/{id}/delete_line_items
Create a credit note
POST /api/v1/billing/credit_notes/create
Create a Credit Note that is linked to an Invoice.
ID of the Invoice.
Reason for issuing this credit note, one of: PRODUCT_RETURN, ORDER_CHANGE, PRODUCT_OR_SERVICE_UNSATISFACTORY, BILLING_ERROR, GOODWILL_GESTURE, OTHER
Unique request ID specified by the merchant.
The type of the credit note, one of: BEFORE_PAYMENT, AFTER_PAYMENT
An explanation for issuing the credit note when the reason is set to OTHER. This field is required if reason is OTHER and must be omitted or null for all other reason values.
Customer-facing text that appears on the credit note PDF.
A set of key-value pairs that you can attach to this object for storing additional information.
Amount credited to decrease the amount of an unpaid invoice.
ID of the Billing Customer.
Time when this credit note was created.
The currency of the credit note (in 3-letter ISO-4217 format).
An explanation for issuing the credit note when the reason enum is set to OTHER. This field is required if the reason is OTHER and must be omitted or null for all other reason values.
Time at which the credit note was finalized.
ID of the Credit Note object.
ID of the Invoice.
Customer-facing text that appears on the credit note PDF.
A set of key-value pairs that you can attach to this object for storing additional information.
A unique number that identifies this particular credit note and appears on the PDF of the credit note and its associated invoice.
Amount credited outside of Airwallex.
The link to download the PDF for the credit note. The URL will be valid for 35 days. If the credit note has not been finalized yet, this will be null.
Reason for issuing this credit note, one of: PRODUCT_RETURN, ORDER_CHANGE, PRODUCT_OR_SERVICE_UNSATISFACTORY, BILLING_ERROR, GOODWILL_GESTURE, OTHER
Amount credited with refund.
Status of the refund, one of CREATED, SUCCEEDED or FAILED. If no refund was created by this Credit Note, the status will be null.
Status of the credit note, one of DRAFT, FINALIZED, and VOIDED.
The total amount of the credit note, including tax.
The aggregate amounts calculated per discount across all credit note line items and the credit note.
The amount of the applied discount.
ID of the Discount object which is applied.
The aggregate amounts calculated per tax rate for all line items.
The type of the credit note, one of: BEFORE_PAYMENT, AFTER_PAYMENT
Time when this credit note was last updated.
Time at which the credit note was voided.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request POST \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/credit_notes/create' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json' \> --data '{> "custom_reason": "Customer requested adjustment",> "invoice_id": "inv_hkpd49cskgblns6iimw",> "memo": "Credit note memo.",> "metadata": {> "foo": "bar"> },> "reason": "PRODUCT_RETURN",> "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",> "type": "BEFORE_PAYMENT">}'
1{2 "adjustment_amount": 50,3 "billing_customer_id": "bcus_hkpd7fedfgb004apkvs",4 "created_at": "2022-01-01T10:15:30+0000",5 "currency": "USD",6 "custom_reason": "Customer requested adjustment",7 "finalized_at": "2022-12-05T10:15:30+0000",8 "id": "crn_hkpda1313adfadfa",9 "invoice_id": "inv_hkpd49cskgblns6iimw",10 "memo": "Credit note memo.",11 "metadata": {12 "foo": "bar"13 },14 "number": "CRN-591726CD-01",15 "out_of_band_amount": 25,16 "pdf_url": "https://creditnote.airwallex.com/billing/creditnotes/pdf?s=jwt_token",17 "reason": "PRODUCT_RETURN",18 "refund_amount": 25,19 "refund_status": "SUCCEEDED",20 "status": "FINALIZED",21 "total_amount": 100,22 "total_discount_amounts": [23 {24 "amount": 10,25 "applied_discount_id": "disc_hkpdkcmxdgazzq53jbk"26 }27 ],28 "total_tax_amount": 0,29 "type": "BEFORE_PAYMENT",30 "updated_at": "2022-01-01T10:15:30+0000",31 "voided_at": "2022-12-05T10:15:30+0000"32}
Preview a credit note
POST /api/v1/billing/credit_notes/preview
Preview a Credit Note that is linked to an Invoice.
ID of the Invoice.
A list of credit note line items to preview.
The amount of the credit note line item. You can specify either the amount directly, or the pair of quantity and unit_amount. When the invoice_line_item_id is null, this amount is proportionally distributed across all invoice line items based on their remaining_creditable_amount.
Description of the line item being credited.
ID of the Invoice Line Item.
A set of key-value pairs that you can attach to this object for storing additional information.
The number of units of product being credited.
Whether the amount or unit_amount are inclusive of taxes or exclusive of taxes. Only can set the value to true for unit_amount when the price of the associated invoice line item is also tax inclusive. Defaults to false.
The amount to be credited per product unit. This unit_amount will be multiplied by the quantity to get the full amount to credit for this line item. You can specify either the amount directly, or the pair of quantity and unit_amount. Only applicable when the invoice_line_item_id is not null.
Defaults to the unit amount of the invoice line item when quantity is provided.
Reason for issuing this credit note, one of: PRODUCT_RETURN, ORDER_CHANGE, PRODUCT_OR_SERVICE_UNSATISFACTORY, BILLING_ERROR, GOODWILL_GESTURE, OTHER
The type of the credit note, one of: BEFORE_PAYMENT, AFTER_PAYMENT
An explanation for issuing the credit note when the reason is set to OTHER. This field is required if reason is OTHER and must be omitted or null for all other reason values.
Customer-facing text that appears on the credit note PDF.
A set of key-value pairs that you can attach to this object for storing additional information.
Amount credited to decrease the amount of an unpaid invoice.
ID of the Billing Customer.
The currency of the credit note (in 3-letter ISO-4217 format).
An explanation for issuing the credit note when the reason enum is set to OTHER. This field is required if the reason is OTHER and must be omitted or null for all other reason values.
ID of the Invoice.
The list of credit note line items in the preview.
The amount of the Credit Note Line Item.
The currency of the Credit Note Line Item in 3-letter ISO-4217 format.
The amount of discount calculated per discount for this credit note line item. The Discount applied to the credit note will be apportioned to the discount_amounts of each credit note line item.
The amount of the applied discount.
ID of the Discount object which is applied.
The tax breakdown details the exact taxes that apply to this line item.
The display name of this tax component.
The amount of tax charged for this component.
The tax percent applied for this component.
The portion of the subtotal that this tax component applies to.
The effective tax percent applied to this line item.
Description of the Credit Note Line Item.
ID of the Invoice Line Item that this credit note line item references.
A set of string key-value pairs that you can attach to this object for storing additional information.
The product quantity.
The tax amount of this line item.
The unit amount of the Credit Note Line Item.
Customer-facing text that appears on the credit note PDF.
A set of key-value pairs that you can attach to this object for storing additional information.
Reason for issuing this credit note, one of: PRODUCT_RETURN, ORDER_CHANGE, PRODUCT_OR_SERVICE_UNSATISFACTORY, BILLING_ERROR, GOODWILL_GESTURE, OTHER
Amount credited with refund.
The total amount of the credit note, including tax.
The aggregate amounts calculated per discount across all credit note line items and the credit note.
The amount of the applied discount.
ID of the Discount object which is applied.
The total tax amount of the credit note.
The type of the credit note, one of: BEFORE_PAYMENT, AFTER_PAYMENT
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request POST \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/credit_notes/preview' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json' \> --data '{> "custom_reason": "Customer requested adjustment",> "invoice_id": "inv_hkpd49cskgblns6iimw",> "line_items": [> {> "amount": 20,> "description": "Customer generated description of the item",> "invoice_line_item_id": "iit_hkpd49cskgblnsnzgm1",> "metadata": {> "foo": "bar"> },> "quantity": 10,> "tax_included": false,> "unit_amount": 2> }> ],> "memo": "Credit note memo.",> "metadata": {> "foo": "bar"> },> "reason": "PRODUCT_RETURN",> "type": "BEFORE_PAYMENT">}'
1{2 "adjustment_amount": 50,3 "billing_customer_id": "bcus_hkpd7fedfgb004apkvs",4 "currency": "USD",5 "custom_reason": "Customer requested adjustment",6 "invoice_id": "inv_hkpd49cskgblns6iimw",7 "line_items": [8 {9 "amount": 10,10 "currency": "CNY",11 "description": "Customer generated description of the item",12 "discount_amounts": [13 {14 "amount": 10,15 "applied_discount_id": "disc_hkpdkcmxdgazzq53jbk"16 }17 ],18 "invoice_line_item_id": "iit_hkpd49cskgblnsnzgm1",19 "metadata": {},20 "quantity": 1,21 "tax_amount": 10,22 "tax_breakdown": [23 {24 "name": "GST",25 "tax_amount": 10,26 "tax_percent": 10,27 "taxable_amount": 10028 }29 ],30 "unit_amount": 1031 }32 ],33 "memo": "Credit note memo.",34 "metadata": {35 "foo": "bar"36 },37 "reason": "PRODUCT_RETURN",38 "refund_amount": 25,39 "total_amount": 110,40 "total_discount_amounts": [41 {42 "amount": 10,43 "applied_discount_id": "disc_hkpdkcmxdgazzq53jbk"44 }45 ],46 "total_tax_amount": 10,47 "type": "BEFORE_PAYMENT"48}
Retrieve a credit note
GET /api/v1/billing/credit_notes/{id}
Retrieves the details of a Credit Note.
ID of the Credit Note object.
Amount credited to decrease the amount of an unpaid invoice.
ID of the Billing Customer.
Time when this credit note was created.
The currency of the credit note (in 3-letter ISO-4217 format).
An explanation for issuing the credit note when the reason enum is set to OTHER. This field is required if the reason is OTHER and must be omitted or null for all other reason values.
Time at which the credit note was finalized.
ID of the Credit Note object.
ID of the Invoice.
Customer-facing text that appears on the credit note PDF.
A set of key-value pairs that you can attach to this object for storing additional information.
A unique number that identifies this particular credit note and appears on the PDF of the credit note and its associated invoice.
Amount credited outside of Airwallex.
The link to download the PDF for the credit note. The URL will be valid for 35 days. If the credit note has not been finalized yet, this will be null.
Reason for issuing this credit note, one of: PRODUCT_RETURN, ORDER_CHANGE, PRODUCT_OR_SERVICE_UNSATISFACTORY, BILLING_ERROR, GOODWILL_GESTURE, OTHER
Amount credited with refund.
Status of the refund, one of CREATED, SUCCEEDED or FAILED. If no refund was created by this Credit Note, the status will be null.
Status of the credit note, one of DRAFT, FINALIZED, and VOIDED.
The total amount of the credit note, including tax.
The aggregate amounts calculated per discount across all credit note line items and the credit note.
The amount of the applied discount.
ID of the Discount object which is applied.
The aggregate amounts calculated per tax rate for all line items.
The type of the credit note, one of: BEFORE_PAYMENT, AFTER_PAYMENT
Time when this credit note was last updated.
Time at which the credit note was voided.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request GET \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/credit_notes/credit_note_id' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json'
1{2 "adjustment_amount": 50,3 "billing_customer_id": "bcus_hkpd7fedfgb004apkvs",4 "created_at": "2022-01-01T10:15:30+0000",5 "currency": "USD",6 "custom_reason": "Customer requested adjustment",7 "finalized_at": "2022-12-05T10:15:30+0000",8 "id": "crn_hkpda1313adfadfa",9 "invoice_id": "inv_hkpd49cskgblns6iimw",10 "memo": "Credit note memo.",11 "metadata": {12 "foo": "bar"13 },14 "number": "CRN-591726CD-01",15 "out_of_band_amount": 25,16 "pdf_url": "https://creditnote.airwallex.com/billing/creditnotes/pdf?s=jwt_token",17 "reason": "PRODUCT_RETURN",18 "refund_amount": 25,19 "refund_status": "SUCCEEDED",20 "status": "FINALIZED",21 "total_amount": 100,22 "total_discount_amounts": [23 {24 "amount": 10,25 "applied_discount_id": "disc_hkpdkcmxdgazzq53jbk"26 }27 ],28 "total_tax_amount": 0,29 "type": "BEFORE_PAYMENT",30 "updated_at": "2022-01-01T10:15:30+0000",31 "voided_at": "2022-12-05T10:15:30+0000"32}
Get list of credit notes
GET /api/v1/billing/credit_notes
Retrieve a list of Credit Notes based on the query parameters.
ID of the billing customer.
The start date of created_at in ISO8601 format (inclusive).
ID of the invoice.
A bookmark for use in pagination to retrieve either the next page or the previous page of results. You can fetch the value for this identifier from the response of the previous API call. To retrieve the next page of results, pass the value of page_after (if not null) from the response to a subsequent call. To retrieve the previous page of results, pass the value of page_before (if not null) from the response to a subsequent call.
Number of Credit Notes to be listed per page. Defaults to 20.
Status of the credit note, one of DRAFT, FINALIZED, and VOIDED.
The end date of created_at in ISO8601 format (exclusive).
The type of the credit note, one of: BEFORE_PAYMENT, AFTER_PAYMENT
Paged results.
Amount credited to decrease the amount of an unpaid invoice.
ID of the Billing Customer.
Time when this credit note was created.
The currency of the credit note (in 3-letter ISO-4217 format).
ID of the Credit Note object.
ID of the Invoice.
A unique number that identifies this particular credit note and appears on the PDF of the credit note and its associated invoice.
Amount credited outside of Airwallex.
Reason for issuing this credit note, one of: PRODUCT_RETURN, ORDER_CHANGE, PRODUCT_OR_SERVICE_UNSATISFACTORY, BILLING_ERROR, GOODWILL_GESTURE, OTHER
Amount credited with refund.
Status of the credit note, one of DRAFT, FINALIZED, and VOIDED.
The total amount of the credit note, including tax.
The aggregate amounts calculated per discount across all credit note line items and the credit note.
The amount of the applied discount.
ID of the Discount object which is applied.
The aggregate amounts calculated per tax rate for all line items.
The type of the credit note, one of: BEFORE_PAYMENT, AFTER_PAYMENT
Time when this credit note was last updated.
An explanation for issuing the credit note when the reason enum is set to OTHER. This field is required if the reason is OTHER and must be omitted or null for all other reason values.
Time at which the credit note was finalized.
Customer-facing text that appears on the credit note PDF.
A set of key-value pairs that you can attach to this object for storing additional information.
The link to download the PDF for the credit note. The URL will be valid for 35 days. If the credit note has not been finalized yet, this will be null.
Status of the refund, one of CREATED, SUCCEEDED or FAILED. If no refund was created by this Credit Note, the status will be null.
Time at which the credit note was voided.
The page cursor used for searching after page.
The page cursor used for search before page.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request GET \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/credit_notes' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json'
1{2 "items": [3 {4 "adjustment_amount": 50,5 "billing_customer_id": "bcus_hkpd7fedfgb004apkvs",6 "created_at": "2022-01-01T10:15:30+0000",7 "currency": "USD",8 "custom_reason": "Customer requested adjustment",9 "finalized_at": "2022-12-05T10:15:30+0000",10 "id": "crn_hkpda1313adfadfa",11 "invoice_id": "inv_hkpd49cskgblns6iimw",12 "memo": "Credit note memo.",13 "metadata": {14 "foo": "bar"15 },16 "number": "CRN-591726CD-01",17 "out_of_band_amount": 25,18 "pdf_url": "https://creditnote.airwallex.com/billing/creditnotes/pdf?s=jwt_token",19 "reason": "PRODUCT_RETURN",20 "refund_amount": 25,21 "refund_status": "SUCCEEDED",22 "status": "FINALIZED",23 "total_amount": 100,24 "total_discount_amounts": [25 {26 "amount": 10,27 "applied_discount_id": "disc_hkpdkcmxdgazzq53jbk"28 }29 ],30 "total_tax_amount": 0,31 "type": "BEFORE_PAYMENT",32 "updated_at": "2022-01-01T10:15:30+0000",33 "voided_at": "2022-12-05T10:15:30+0000"34 }35 ],36 "page_after": "<string>",37 "page_before": "<string>"38}
Update a credit note
POST /api/v1/billing/credit_notes/{id}/update
Update a draft Credit Note.
ID of the Credit Note object.
An explanation for issuing the credit note when the reason enum is set to OTHER. This field is required if reason is OTHER and must be omitted or null for all other reason values.
Customer-facing text that appears on the credit note PDF.
A set of key-value pairs that you can attach to this object for storing additional information.
Reason for issuing this credit note, one of: PRODUCT_RETURN, ORDER_CHANGE, PRODUCT_OR_SERVICE_UNSATISFACTORY, BILLING_ERROR, GOODWILL_GESTURE, OTHER
Amount credited to decrease the amount of an unpaid invoice.
ID of the Billing Customer.
Time when this credit note was created.
The currency of the credit note (in 3-letter ISO-4217 format).
An explanation for issuing the credit note when the reason enum is set to OTHER. This field is required if the reason is OTHER and must be omitted or null for all other reason values.
Time at which the credit note was finalized.
ID of the Credit Note object.
ID of the Invoice.
Customer-facing text that appears on the credit note PDF.
A set of key-value pairs that you can attach to this object for storing additional information.
A unique number that identifies this particular credit note and appears on the PDF of the credit note and its associated invoice.
Amount credited outside of Airwallex.
The link to download the PDF for the credit note. The URL will be valid for 35 days. If the credit note has not been finalized yet, this will be null.
Reason for issuing this credit note, one of: PRODUCT_RETURN, ORDER_CHANGE, PRODUCT_OR_SERVICE_UNSATISFACTORY, BILLING_ERROR, GOODWILL_GESTURE, OTHER
Amount credited with refund.
Status of the refund, one of CREATED, SUCCEEDED or FAILED. If no refund was created by this Credit Note, the status will be null.
Status of the credit note, one of DRAFT, FINALIZED, and VOIDED.
The total amount of the credit note, including tax.
The aggregate amounts calculated per discount across all credit note line items and the credit note.
The amount of the applied discount.
ID of the Discount object which is applied.
The aggregate amounts calculated per tax rate for all line items.
The type of the credit note, one of: BEFORE_PAYMENT, AFTER_PAYMENT
Time when this credit note was last updated.
Time at which the credit note was voided.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request POST \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/credit_notes/credit_note_id/update' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json' \> --data '{> "custom_reason": "Customer requested adjustment",> "memo": "Updated credit note memo.",> "metadata": {> "foo": "bar"> },> "reason": "PRODUCT_RETURN">}'
1{2 "adjustment_amount": 50,3 "billing_customer_id": "bcus_hkpd7fedfgb004apkvs",4 "created_at": "2022-01-01T10:15:30+0000",5 "currency": "USD",6 "custom_reason": "Customer requested adjustment",7 "finalized_at": "2022-12-05T10:15:30+0000",8 "id": "crn_hkpda1313adfadfa",9 "invoice_id": "inv_hkpd49cskgblns6iimw",10 "memo": "Credit note memo.",11 "metadata": {12 "foo": "bar"13 },14 "number": "CRN-591726CD-01",15 "out_of_band_amount": 25,16 "pdf_url": "https://creditnote.airwallex.com/billing/creditnotes/pdf?s=jwt_token",17 "reason": "PRODUCT_RETURN",18 "refund_amount": 25,19 "refund_status": "SUCCEEDED",20 "status": "FINALIZED",21 "total_amount": 100,22 "total_discount_amounts": [23 {24 "amount": 10,25 "applied_discount_id": "disc_hkpdkcmxdgazzq53jbk"26 }27 ],28 "total_tax_amount": 0,29 "type": "BEFORE_PAYMENT",30 "updated_at": "2022-01-01T10:15:30+0000",31 "voided_at": "2022-12-05T10:15:30+0000"32}
Finalize a credit note
POST /api/v1/billing/credit_notes/{id}/finalize
Finalize a draft Credit Note. If the type is BEFORE_PAYMENT, the refund_amount and out_of_band_amount must be null. If the type is AFTER_PAYMENT, you will need to allocate the total_amount of the credit note to either refund_amount or out_of_band_amount.
ID of the Credit Note object.
Amount credited outside of Airwallex. Only applicable when the type is AFTER_PAYMENT.
Amount credited with refund. Only applicable when the type is AFTER_PAYMENT.
Amount credited to decrease the amount of an unpaid invoice.
ID of the Billing Customer.
Time when this credit note was created.
The currency of the credit note (in 3-letter ISO-4217 format).
An explanation for issuing the credit note when the reason enum is set to OTHER. This field is required if the reason is OTHER and must be omitted or null for all other reason values.
Time at which the credit note was finalized.
ID of the Credit Note object.
ID of the Invoice.
Customer-facing text that appears on the credit note PDF.
A set of key-value pairs that you can attach to this object for storing additional information.
A unique number that identifies this particular credit note and appears on the PDF of the credit note and its associated invoice.
Amount credited outside of Airwallex.
The link to download the PDF for the credit note. The URL will be valid for 35 days. If the credit note has not been finalized yet, this will be null.
Reason for issuing this credit note, one of: PRODUCT_RETURN, ORDER_CHANGE, PRODUCT_OR_SERVICE_UNSATISFACTORY, BILLING_ERROR, GOODWILL_GESTURE, OTHER
Amount credited with refund.
Status of the refund, one of CREATED, SUCCEEDED or FAILED. If no refund was created by this Credit Note, the status will be null.
Status of the credit note, one of DRAFT, FINALIZED, and VOIDED.
The total amount of the credit note, including tax.
The aggregate amounts calculated per discount across all credit note line items and the credit note.
The amount of the applied discount.
ID of the Discount object which is applied.
The aggregate amounts calculated per tax rate for all line items.
The type of the credit note, one of: BEFORE_PAYMENT, AFTER_PAYMENT
Time when this credit note was last updated.
Time at which the credit note was voided.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request POST \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/credit_notes/credit_note_id/finalize' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json' \> --data '{> "out_of_band_amount": 0,> "refund_amount": 100.3>}'
1{2 "adjustment_amount": 50,3 "billing_customer_id": "bcus_hkpd7fedfgb004apkvs",4 "created_at": "2022-01-01T10:15:30+0000",5 "currency": "USD",6 "custom_reason": "Customer requested adjustment",7 "finalized_at": "2022-12-05T10:15:30+0000",8 "id": "crn_hkpda1313adfadfa",9 "invoice_id": "inv_hkpd49cskgblns6iimw",10 "memo": "Credit note memo.",11 "metadata": {12 "foo": "bar"13 },14 "number": "CRN-591726CD-01",15 "out_of_band_amount": 25,16 "pdf_url": "https://creditnote.airwallex.com/billing/creditnotes/pdf?s=jwt_token",17 "reason": "PRODUCT_RETURN",18 "refund_amount": 25,19 "refund_status": "SUCCEEDED",20 "status": "FINALIZED",21 "total_amount": 100,22 "total_discount_amounts": [23 {24 "amount": 10,25 "applied_discount_id": "disc_hkpdkcmxdgazzq53jbk"26 }27 ],28 "total_tax_amount": 0,29 "type": "BEFORE_PAYMENT",30 "updated_at": "2022-01-01T10:15:30+0000",31 "voided_at": "2022-12-05T10:15:30+0000"32}
Delete a credit note
POST /api/v1/billing/credit_notes/{id}/delete
Delete a draft Credit Note.
ID of the Credit Note object.
Indicates whether the delete command was executed successfully.
ID of the Credit Note object.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request POST \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/credit_notes/credit_note_id/delete' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json'
1{2 "deleted": true,3 "id": "crn_hkpda1313adfadfa"4}
Void a credit note
POST /api/v1/billing/credit_notes/{id}/void
Void a finalized Credit Note. Transition from finalized to voided is allowed only when: 1) type of Credit Note is pre-payment 2) payment status of the linked Invoice is unpaid.
ID of the Credit Note object.
Amount credited to decrease the amount of an unpaid invoice.
ID of the Billing Customer.
Time when this credit note was created.
The currency of the credit note (in 3-letter ISO-4217 format).
An explanation for issuing the credit note when the reason enum is set to OTHER. This field is required if the reason is OTHER and must be omitted or null for all other reason values.
Time at which the credit note was finalized.
ID of the Credit Note object.
ID of the Invoice.
Customer-facing text that appears on the credit note PDF.
A set of key-value pairs that you can attach to this object for storing additional information.
A unique number that identifies this particular credit note and appears on the PDF of the credit note and its associated invoice.
Amount credited outside of Airwallex.
The link to download the PDF for the credit note. The URL will be valid for 35 days. If the credit note has not been finalized yet, this will be null.
Reason for issuing this credit note, one of: PRODUCT_RETURN, ORDER_CHANGE, PRODUCT_OR_SERVICE_UNSATISFACTORY, BILLING_ERROR, GOODWILL_GESTURE, OTHER
Amount credited with refund.
Status of the refund, one of CREATED, SUCCEEDED or FAILED. If no refund was created by this Credit Note, the status will be null.
Status of the credit note, one of DRAFT, FINALIZED, and VOIDED.
The total amount of the credit note, including tax.
The aggregate amounts calculated per discount across all credit note line items and the credit note.
The amount of the applied discount.
ID of the Discount object which is applied.
The aggregate amounts calculated per tax rate for all line items.
The type of the credit note, one of: BEFORE_PAYMENT, AFTER_PAYMENT
Time when this credit note was last updated.
Time at which the credit note was voided.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request POST \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/credit_notes/credit_note_id/void' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json'
1{2 "adjustment_amount": 50,3 "billing_customer_id": "bcus_hkpd7fedfgb004apkvs",4 "created_at": "2022-01-01T10:15:30+0000",5 "currency": "USD",6 "custom_reason": "Customer requested adjustment",7 "finalized_at": "2022-12-05T10:15:30+0000",8 "id": "crn_hkpda1313adfadfa",9 "invoice_id": "inv_hkpd49cskgblns6iimw",10 "memo": "Credit note memo.",11 "metadata": {12 "foo": "bar"13 },14 "number": "CRN-591726CD-01",15 "out_of_band_amount": 25,16 "pdf_url": "https://creditnote.airwallex.com/billing/creditnotes/pdf?s=jwt_token",17 "reason": "PRODUCT_RETURN",18 "refund_amount": 25,19 "refund_status": "SUCCEEDED",20 "status": "FINALIZED",21 "total_amount": 100,22 "total_discount_amounts": [23 {24 "amount": 10,25 "applied_discount_id": "disc_hkpdkcmxdgazzq53jbk"26 }27 ],28 "total_tax_amount": 0,29 "type": "BEFORE_PAYMENT",30 "updated_at": "2022-01-01T10:15:30+0000",31 "voided_at": "2022-12-05T10:15:30+0000"32}
Create credit note line items and add them to a credit note
POST /api/v1/billing/credit_notes/{id}/add_line_items
Create Line Items and add them to a Credit Note. This is only possible when the Credit Note status is DRAFT. You can only add 100 line items at a time. The bulk create operation is atomic, all the line items created with the request will either succeed or fail together.
ID of the Credit Note object.
A list of credit note line items to be added, you may add 100 items at a time and add up to a maximum of 1000 items per credit note.
The amount of the credit note line item. You can specify either the amount directly, or the pair of quantity and unit_amount. When the invoice_line_item_id is null, this amount is proportionally distributed across all invoice line items based on their remaining_creditable_amount.
Description of the line item being credited.
ID of the Invoice Line Item.
A set of key-value pairs that you can attach to this object for storing additional information.
The number of units of product being credited.
Whether the amount or unit_amount are inclusive of taxes or exclusive of taxes. Only can set the value to true for unit_amount when the price of the associated invoice line item is also tax inclusive. Defaults to false.
The amount to be credited per product unit. This unit_amount will be multiplied by the quantity to get the full amount to credit for this line item. You can specify either the amount directly, or the pair of quantity and unit_amount. Only applicable when the invoice_line_item_id is not null.
Defaults to the unit amount of the invoice line item when quantity is provided.
Unique request ID specified by the merchant.
Amount credited to decrease the amount of an unpaid invoice.
ID of the Billing Customer.
Time when this credit note was created.
The currency of the credit note (in 3-letter ISO-4217 format).
An explanation for issuing the credit note when the reason enum is set to OTHER. This field is required if the reason is OTHER and must be omitted or null for all other reason values.
Time at which the credit note was finalized.
ID of the Credit Note object.
ID of the Invoice.
Customer-facing text that appears on the credit note PDF.
A set of key-value pairs that you can attach to this object for storing additional information.
A unique number that identifies this particular credit note and appears on the PDF of the credit note and its associated invoice.
Amount credited outside of Airwallex.
The link to download the PDF for the credit note. The URL will be valid for 35 days. If the credit note has not been finalized yet, this will be null.
Reason for issuing this credit note, one of: PRODUCT_RETURN, ORDER_CHANGE, PRODUCT_OR_SERVICE_UNSATISFACTORY, BILLING_ERROR, GOODWILL_GESTURE, OTHER
Amount credited with refund.
Status of the refund, one of CREATED, SUCCEEDED or FAILED. If no refund was created by this Credit Note, the status will be null.
Status of the credit note, one of DRAFT, FINALIZED, and VOIDED.
The total amount of the credit note, including tax.
The aggregate amounts calculated per discount across all credit note line items and the credit note.
The amount of the applied discount.
ID of the Discount object which is applied.
The aggregate amounts calculated per tax rate for all line items.
The type of the credit note, one of: BEFORE_PAYMENT, AFTER_PAYMENT
Time when this credit note was last updated.
Time at which the credit note was voided.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request POST \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/credit_notes/credit_note_id/add_line_items' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json' \> --data '{> "line_items": [> {> "amount": 20,> "description": "Customer generated description of the item",> "invoice_line_item_id": "iit_hkpd49cskgblnsnzgm1",> "metadata": {> "foo": "bar"> },> "quantity": 10,> "tax_included": false,> "unit_amount": 2> }> ],> "request_id": "ee939540-3203-4a2c-9172-89a566485dd9">}'
1{2 "adjustment_amount": 50,3 "billing_customer_id": "bcus_hkpd7fedfgb004apkvs",4 "created_at": "2022-01-01T10:15:30+0000",5 "currency": "USD",6 "custom_reason": "Customer requested adjustment",7 "finalized_at": "2022-12-05T10:15:30+0000",8 "id": "crn_hkpda1313adfadfa",9 "invoice_id": "inv_hkpd49cskgblns6iimw",10 "memo": "Credit note memo.",11 "metadata": {12 "foo": "bar"13 },14 "number": "CRN-591726CD-01",15 "out_of_band_amount": 25,16 "pdf_url": "https://creditnote.airwallex.com/billing/creditnotes/pdf?s=jwt_token",17 "reason": "PRODUCT_RETURN",18 "refund_amount": 25,19 "refund_status": "SUCCEEDED",20 "status": "FINALIZED",21 "total_amount": 100,22 "total_discount_amounts": [23 {24 "amount": 10,25 "applied_discount_id": "disc_hkpdkcmxdgazzq53jbk"26 }27 ],28 "total_tax_amount": 0,29 "type": "BEFORE_PAYMENT",30 "updated_at": "2022-01-01T10:15:30+0000",31 "voided_at": "2022-12-05T10:15:30+0000"32}
Retrieve a credit note line item
GET /api/v1/billing/credit_notes/{id}/line_items/{line_item_id}
Retrieves the details of a Credit Note Line Item.
ID of the Credit Note object that this Credit Note Line Item belongs to.
ID of the Credit Note Line Item object.
The amount of the Credit Note Line Item.
Time when the Credit Note Line Item was created.
ID of the Credit Note that this Credit Note Line Item belongs to.
The currency of the Credit Note Line Item in 3-letter ISO-4217 format.
Description of the Credit Note Line Item.
The amount of discount calculated per discount for this credit note line item. The Discount applied to the credit note will be apportioned to the discount_amounts of each credit note line item.
The amount of the applied discount.
ID of the Discount object which is applied.
ID of the Credit Note Line Item object.
ID of the Invoice Line Item that this credit note line item references.
A set of string key-value pairs that you can attach to this object for storing additional information.
The product quantity.
The tax amount of this line item.
The tax breakdown details the exact taxes that apply to this line item.
The display name of this tax component.
The amount of tax charged for this component.
The tax percent applied for this component.
The portion of the subtotal that this tax component applies to.
The effective tax percent applied to this line item.
The unit amount of the Credit Note Line Item.
Time when the Credit Note Line Item was last updated.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request GET \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/credit_notes/credit_note_id/line_items/line_item_id' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json'
1{2 "amount": 10,3 "created_at": "2025-01-01T00:00:00+0000",4 "credit_note_id": "crn_hkpda1313adfadfa",5 "currency": "CNY",6 "description": "Customer generated description of the item",7 "discount_amounts": [8 {9 "amount": 10,10 "applied_discount_id": "disc_hkpdkcmxdgazzq53jbk"11 }12 ],13 "id": "cnit_hkpd49cskgblnsnzgm1",14 "invoice_line_item_id": "iit_hkpd49cskgblnsnzgm1",15 "metadata": {},16 "quantity": 1,17 "tax_amount": 10,18 "tax_breakdown": [19 {20 "name": "GST",21 "tax_amount": 10,22 "tax_percent": 10,23 "taxable_amount": 10024 }25 ],26 "tax_percent": 0,27 "unit_amount": 10,28 "updated_at": "2025-01-01T00:00:00+0000"29}
Get list of credit note line items
GET /api/v1/billing/credit_notes/{id}/line_items
Retrieves a list of Credit Note Line Items based on the query parameters.
ID of the Credit Note object that the Credit Note Line Items belong to.
A bookmark for use in pagination to retrieve either the next page or the previous page of results. You can fetch the value for this identifier from the response of the previous API call. To retrieve the next page of results, pass the value of page_after (if not null) from the response to a subsequent call. To retrieve the previous page of results, pass the value of page_before (if not null) from the response to a subsequent call.
Number of Credit Note Line Items per page. Defaults to 20.
Paged results.
The amount of the Credit Note Line Item.
Time when the Credit Note Line Item was created.
ID of the Credit Note that this Credit Note Line Item belongs to.
The currency of the Credit Note Line Item in 3-letter ISO-4217 format.
The amount of discount calculated per discount for this credit note line item. The Discount applied to the credit note will be apportioned to the discount_amounts of each credit note line item.
The amount of the applied discount.
ID of the Discount object which is applied.
ID of the Credit Note Line Item object.
The tax breakdown details the exact taxes that apply to this line item.
The display name of this tax component.
The amount of tax charged for this component.
The tax percent applied for this component.
The portion of the subtotal that this tax component applies to.
The effective tax percent applied to this line item.
Time when the Credit Note Line Item was last updated.
Description of the Credit Note Line Item.
ID of the Invoice Line Item that this credit note line item references.
A set of string key-value pairs that you can attach to this object for storing additional information.
The product quantity.
The tax amount of this line item.
The unit amount of the Credit Note Line Item.
The page cursor used for searching after page.
The page cursor used for search before page.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request GET \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/credit_notes/credit_note_id/line_items' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json'
1{2 "items": [3 {4 "amount": 10,5 "created_at": "2025-01-01T00:00:00+0000",6 "credit_note_id": "crn_hkpda1313adfadfa",7 "currency": "CNY",8 "description": "Customer generated description of the item",9 "discount_amounts": [10 {11 "amount": 10,12 "applied_discount_id": "disc_hkpdkcmxdgazzq53jbk"13 }14 ],15 "id": "cnit_hkpd49cskgblnsnzgm1",16 "invoice_line_item_id": "iit_hkpd49cskgblnsnzgm1",17 "metadata": {},18 "quantity": 1,19 "tax_amount": 10,20 "tax_breakdown": [21 {22 "name": "GST",23 "tax_amount": 10,24 "tax_percent": 10,25 "taxable_amount": 10026 }27 ],28 "unit_amount": 10,29 "updated_at": "2025-01-01T00:00:00+0000"30 }31 ],32 "page_after": "<string>",33 "page_before": "<string>"34}
Update credit note line items in a credit note
POST /api/v1/billing/credit_notes/{id}/update_line_items
Update Line Items in a Credit Note. This is only possible when the Credit Note status is DRAFT. You can only update 100 line items at a time. The bulk update operation is atomic, all the updates in the request will either succeed or fail together.
ID of the Credit Note object.
A list of credit note line items to be updated, you may update 100 items at a time.
ID of the credit note line item object.
The amount of the credit note line item. Only applicable when both the unit_amount and quantity are null.
Description of the line item being credited.
A set of key-value pairs that you can attach to this object for storing additional information.
The number of units of product being credited.
Whether the amount or unit_amount are inclusive of taxes or exclusive of taxes.
The amount to be credited per product unit. This unit_amount will be multiplied by the quantity to get the full amount to credit for this line item.
Amount credited to decrease the amount of an unpaid invoice.
ID of the Billing Customer.
Time when this credit note was created.
The currency of the credit note (in 3-letter ISO-4217 format).
An explanation for issuing the credit note when the reason enum is set to OTHER. This field is required if the reason is OTHER and must be omitted or null for all other reason values.
Time at which the credit note was finalized.
ID of the Credit Note object.
ID of the Invoice.
Customer-facing text that appears on the credit note PDF.
A set of key-value pairs that you can attach to this object for storing additional information.
A unique number that identifies this particular credit note and appears on the PDF of the credit note and its associated invoice.
Amount credited outside of Airwallex.
The link to download the PDF for the credit note. The URL will be valid for 35 days. If the credit note has not been finalized yet, this will be null.
Reason for issuing this credit note, one of: PRODUCT_RETURN, ORDER_CHANGE, PRODUCT_OR_SERVICE_UNSATISFACTORY, BILLING_ERROR, GOODWILL_GESTURE, OTHER
Amount credited with refund.
Status of the refund, one of CREATED, SUCCEEDED or FAILED. If no refund was created by this Credit Note, the status will be null.
Status of the credit note, one of DRAFT, FINALIZED, and VOIDED.
The total amount of the credit note, including tax.
The aggregate amounts calculated per discount across all credit note line items and the credit note.
The amount of the applied discount.
ID of the Discount object which is applied.
The aggregate amounts calculated per tax rate for all line items.
The type of the credit note, one of: BEFORE_PAYMENT, AFTER_PAYMENT
Time when this credit note was last updated.
Time at which the credit note was voided.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request POST \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/credit_notes/credit_note_id/update_line_items' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json' \> --data '{> "line_items": [> {> "amount": 30,> "description": "Customer generated description of the item",> "id": "cnit_hkpd49cskgblnsnzgm1",> "metadata": {> "foo": "bar"> },> "quantity": 2,> "tax_included": false,> "unit_amount": 2> }> ]>}'
1{2 "adjustment_amount": 50,3 "billing_customer_id": "bcus_hkpd7fedfgb004apkvs",4 "created_at": "2022-01-01T10:15:30+0000",5 "currency": "USD",6 "custom_reason": "Customer requested adjustment",7 "finalized_at": "2022-12-05T10:15:30+0000",8 "id": "crn_hkpda1313adfadfa",9 "invoice_id": "inv_hkpd49cskgblns6iimw",10 "memo": "Credit note memo.",11 "metadata": {12 "foo": "bar"13 },14 "number": "CRN-591726CD-01",15 "out_of_band_amount": 25,16 "pdf_url": "https://creditnote.airwallex.com/billing/creditnotes/pdf?s=jwt_token",17 "reason": "PRODUCT_RETURN",18 "refund_amount": 25,19 "refund_status": "SUCCEEDED",20 "status": "FINALIZED",21 "total_amount": 100,22 "total_discount_amounts": [23 {24 "amount": 10,25 "applied_discount_id": "disc_hkpdkcmxdgazzq53jbk"26 }27 ],28 "total_tax_amount": 0,29 "type": "BEFORE_PAYMENT",30 "updated_at": "2022-01-01T10:15:30+0000",31 "voided_at": "2022-12-05T10:15:30+0000"32}
Delete credit note line items from a credit note
POST /api/v1/billing/credit_notes/{id}/delete_line_items
Delete Line Items in a Credit Note. This is only possible when the Credit Note status is DRAFT. You can only delete 100 line items at a time. The bulk delete operation is atomic, all the removals in the request will either succeed or fail together.
ID of the Credit Note object.
List of Credit Note Line Item IDs to be deleted.
Amount credited to decrease the amount of an unpaid invoice.
ID of the Billing Customer.
Time when this credit note was created.
The currency of the credit note (in 3-letter ISO-4217 format).
An explanation for issuing the credit note when the reason enum is set to OTHER. This field is required if the reason is OTHER and must be omitted or null for all other reason values.
Time at which the credit note was finalized.
ID of the Credit Note object.
ID of the Invoice.
Customer-facing text that appears on the credit note PDF.
A set of key-value pairs that you can attach to this object for storing additional information.
A unique number that identifies this particular credit note and appears on the PDF of the credit note and its associated invoice.
Amount credited outside of Airwallex.
The link to download the PDF for the credit note. The URL will be valid for 35 days. If the credit note has not been finalized yet, this will be null.
Reason for issuing this credit note, one of: PRODUCT_RETURN, ORDER_CHANGE, PRODUCT_OR_SERVICE_UNSATISFACTORY, BILLING_ERROR, GOODWILL_GESTURE, OTHER
Amount credited with refund.
Status of the refund, one of CREATED, SUCCEEDED or FAILED. If no refund was created by this Credit Note, the status will be null.
Status of the credit note, one of DRAFT, FINALIZED, and VOIDED.
The total amount of the credit note, including tax.
The aggregate amounts calculated per discount across all credit note line items and the credit note.
The amount of the applied discount.
ID of the Discount object which is applied.
The aggregate amounts calculated per tax rate for all line items.
The type of the credit note, one of: BEFORE_PAYMENT, AFTER_PAYMENT
Time when this credit note was last updated.
Time at which the credit note was voided.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request POST \> --url 'https://api.sandbox.airwallex.com/api/v1/billing/credit_notes/credit_note_id/delete_line_items' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json' \> --data '{> "line_item_ids": [> "cnit_hkpd49cskgblnsnzgm1",> "cnit_hkpd49cskgblnsnzgm2"> ]>}'
1{2 "adjustment_amount": 50,3 "billing_customer_id": "bcus_hkpd7fedfgb004apkvs",4 "created_at": "2022-01-01T10:15:30+0000",5 "currency": "USD",6 "custom_reason": "Customer requested adjustment",7 "finalized_at": "2022-12-05T10:15:30+0000",8 "id": "crn_hkpda1313adfadfa",9 "invoice_id": "inv_hkpd49cskgblns6iimw",10 "memo": "Credit note memo.",11 "metadata": {12 "foo": "bar"13 },14 "number": "CRN-591726CD-01",15 "out_of_band_amount": 25,16 "pdf_url": "https://creditnote.airwallex.com/billing/creditnotes/pdf?s=jwt_token",17 "reason": "PRODUCT_RETURN",18 "refund_amount": 25,19 "refund_status": "SUCCEEDED",20 "status": "FINALIZED",21 "total_amount": 100,22 "total_discount_amounts": [23 {24 "amount": 10,25 "applied_discount_id": "disc_hkpdkcmxdgazzq53jbk"26 }27 ],28 "total_tax_amount": 0,29 "type": "BEFORE_PAYMENT",30 "updated_at": "2022-01-01T10:15:30+0000",31 "voided_at": "2022-12-05T10:15:30+0000"32}