Skip to main content
Limited Release
Credit note management helps you track and control credit notes after you create them. You can list credit notes with filters, retrieve detailed information, and void credit notes when necessary.

​
List credit notes

Use a valid access token and make a GET call to the /v1/commerce/billing/credit-notes endpoint. Include the following query parameters:
ParameterAction
page
integer		Set the page number for paginated results. Default is 1.
per_page
integer		Set the number of credit notes to return per page. Default is 10, maximum is 100.
status
string		Filter credit notes by status.

Possible values: DRAFT, FINALIZED, VOIDED
credit_status
string		Filter credit notes by credit status.

Possible values: AVAILABLE, CONSUMED, VOIDED
refund_status
string		Filter credit notes by refund status.

Possible values: PENDING, SUCCEEDED, FAILED
reason
string		Filter credit notes by reason.

Possible values: DUPLICATED_CHARGE, PRODUCT_UNSATISFACTORY, ORDER_CHANGE, ORDER_CANCELLATION, FRAUDULENT_CHARGE, OTHER
issuing_date_from
string		Set the start date to filter credit notes issued from this date (YYYY-MM-DD format).
issuing_date_to
string		Set the end date to filter credit notes issued until this date (YYYY-MM-DD format).
external_customer_id
string		Set to the external_id returned when you registered the customer to filter credit notes for that customer.
invoice_id
string		Set to the id returned when you listed the invoices to filter credit notes for that invoice.
For information on all parameters, see API reference. 
curl -X GET 'https://api-m.sandbox.paypal.com/v1/commerce/billing/credit-notes?per_page=10&page=1&status=FINALIZED&credit_status=AVAILABLE&refund_status=SUCCEEDED&reason=ORDER_CANCELLATION&issuing_date_from=2023-01-01&issuing_date_to=2023-12-31&external_customer_id=cust_123&invoice_id=inv_01H2XT1G7N8E2JHJKBVPDS0TQD' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>'
A successful call returns a 200 OK response with a paginated list of credit notes.

​
Get credit note details

Use a valid access token and make a GET call to the /v1/commerce/billing/credit-notes/{credit_note_id} endpoint. Path parameter: credit_note_id is the id returned in the List credit notes response. 
curl -X GET 'https://api-m.sandbox.paypal.com/v1/commerce/billing/credit-notes/cn_01H2XT1G7N8E2JHJKBVPDS0TQD' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>'
A successful call returns a 200 OK response with the credit note details.

​
Void credit notes

Use a valid access token and make a POST call to the /v1/commerce/billing/credit-notes/{credit_note_id}/void endpoint. When you void a credit note, you make it no longer available for use. You cannot undo this action. Path parameter: credit_note_id is the id returned in the List credit notes response. 
curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/credit-notes/cn_01H2XT1G7N8E2JHJKBVPDS0TQD/void' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>'
A successful call returns a 200 OK response with the voided credit note details.