Skip to main content
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 with optional query parameters to filter results.

​
Query parameters

Parameter nameDescription
page
integer		Page number for pagination. Default is 1.
per_page
integer		Number of credit notes per page. Default is 10, maximum is 100.
status
string		Filter credit notes by its status.

Possible values:
DRAFT: Credit note is in draft state and can be modified
FINALIZED: Credit note has been finalized and cannot be modified
VOIDED: Credit note has been voided and is no longer valid
credit_status
string		Filter credit notes by credit status.

Possible values:
AVAILABLE: Credit amount remains available for future usage
CONSUMED: Credit amount has been fully consumed
VOIDED: Credit has been voided and is no longer available
refund_status
string		Filter credit notes by refund status.

Possible values:
PENDING: Refund is pending execution
SUCCEEDED: Refund has been successfully executed
FAILED: Refund has failed and was not processed
reason
string		Filter credit notes by reason.

Possible values:
DUPLICATED_CHARGE: Duplicate charge on customer account
PRODUCT_UNSATISFACTORY: Product or service was unsatisfactory
ORDER_CHANGE: Changes made to the original order
ORDER_CANCELLATION: Order was cancelled
FRAUDULENT_CHARGE: Fraudulent or unauthorized charge
OTHER: Other reasons not covered by standard categories
issuing_date_from
string		Filter credit notes issued from this date (YYYY-MM-DD format).
issuing_date_to
string		Filter credit notes issued until this date (YYYY-MM-DD format).
external_customer_id
string		Filter credit notes by external customer ID. Use the external_id you provided when you registered the customer.
invoice_id
string		Filter credit notes by invoice ID. Use the id returned when PayPal generates invoices.
On successful request processing, PayPal returns a paginated list of credit notes. 
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>'
For the exhaustive list of response parameters, see API reference.

​
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. On successful request processing, PayPal returns detailed credit note information. 
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>'
For the exhaustive list of response parameters, see API reference.

​
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. Path parameter: credit_note_id is the id returned in the List credit notes response. When you void a credit note, you make it no longer available for use. You cannot undo this action. On successful request processing, PayPal returns the updated credit note with voided status. 
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>'
For the exhaustive list of response parameters, see API reference.