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 send a GET request to /v1/commerce/billing/credit-notes 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, the one returned when you registered a customer.
invoice_id
string		Filter credit notes by invoice ID, the one assigned 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>'
Note: For the exhaustive list of query and response parameters, see API reference.

​
Get credit note details

Use a valid access token and send a GET request to /v1/commerce/billing/credit-notes/{id}. Path parameter: id is the credit note identifier that List credit notes returns. 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>'
Note: For the exhaustive list of response parameters, see API reference.

​
Void credit notes

Use a valid access token and send a POST request to /v1/commerce/billing/credit-notes/{id}/void. Path parameter: id is the credit note identifier that List credit notes returns. 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>'
Note: For the exhaustive list of response parameters, see API reference.
⌘I