Skip to main content
Limited Release
Payment retry: PayPal generates invoices for your customers’ usage. As part of handling payment exceptions, you can retrieve the list of invoices with failed payment status and troubleshoot the issues. After you fix the problems, you can retry payments. Reconciliation and refunds: Reconciliation involves comparing your billing records with actual usage data and payments to find discrepancies. After reconciliation, you may need to refund customers for billing adjustments. Common discrepancies include overcharges, duplicate charges, service interruptions, or pricing errors. To refund customers for these billing adjustments after invoice generation and payment processing, you can create credit notes. Credit notes can do the following:
  • Send refunds: Returns money directly to the customer’s payment method. Customers receive the refund immediately.
  • Add credits: Returns credits to the customer’s credit wallet. PayPal auto-creates this wallet. PayPal consumes these credits during future billing.
A single credit note can include both refund and credit amounts, giving you flexibility to split adjustments between immediate refunds and future account credits.

​
Retry payment for an invoice

Use a valid access token and make a POST call to the /v1/commerce/billing/invoices/{invoice_id}/retry_payment endpoint. Path parameter: invoice_id is the id returned in the List invoices response. On successful request processing, PayPal returns 204 No Content. 
curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/invoices/9cf09b3f-9e52-434c-b3f4-3675739795fa/retry_payment' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>'

​
Create credit notes

A credit note is a billing adjustment document that reduces or reverses charges on an existing invoice. While an invoice charges customers, a credit note returns money or provides account credits. Create credit notes when you need to correct billing after invoices have been issued. Each credit note references a specific invoice and can include both refund and credit amounts in a single adjustment.
If refunds or credit amounts are not explicitly called out, the fee specified by the credit note is added as credits by default.
Use a valid access token and make a POST call to the /v1/commerce/billing/credit-notes endpoint with the required request parameters. On successful request processing, PayPal returns the created credit note details. 
curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/credit-notes' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>' \
    -d '{
      "invoice_id": "a783c33f-acd4-4b34-b23c-77c0603e718e",
      "reason": "DUPLICATED_CHARGE",
      "description": "Refund for duplicated charge",
      "credit_amount": {
        "value": 25.00
      },
      "refund_amount": {
        "value": 25.00
      },
      "items": [
        {
          "fee_id": "6b873676-30ae-4ff9-846c-4b6ef4073e95",
          "amount": {
            "value": 50.00
          }
        }
      ]
    }'

​
Request body parameters

Parameter nameDescription
invoice_id
Required, string		Unique identifier that identifies the invoice. Use the id returned in the List invoices response.
reason
string		The reason for credit note creation.

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
description
string		Description of the credit note for internal reference.
credit_amount
object		The total amount to be credited to the customer balance for future use. Only include value field (currency is inherited from invoice).
refund_amount
object		The total amount to be refunded to the customer immediately. Only include value field (currency is inherited from invoice).
items
Required, array		Array of credit note items specifying which fees to credit or refund. Minimum 1 item required.
items[].fee_id
Required, string		The fee unique identifier (UUID format) from the original invoice.
items[].amount
Required, object		The amount of the credit note item to be processed. Only include value field.

​
Response parameters

This section documents only the response parameters relevant for the next step. For the exhaustive list of response parameters, see API reference.
Parameter nameDescription and further action
id
string		Unique identifier for the credit note.
Use this id in future operations, such as when getting credit note details or voiding the credit note.
billing_entity_code
string		The billing entity code associated with this credit note.
number
string		The formatted credit note number for reference and tracking.
credit_status
string		Status of the credit amount.

Possible values: AVAILABLE, CONSUMED, VOIDED.
refund_status
string		Status of the refund amount.

Possible values: PENDING, SUCCEEDED, FAILED, CANCELED.
items
array		Detailed breakdown of the credit note items with their associated fees.

​
Manage credit notes

Possible management actionImpact
Void credit note: Permanently delete a credit note, making it no longer available for use.Changes status to VOIDED and prevents further credit application to pay charges.