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. 
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>'
A successful call returns a 204 No Content response.

​
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. Include the following parameters:
ParameterAction
invoice_id
Required, string		Set to the id returned when you listed the invoices.
reason
string		Set the reason for credit note creation.

Possible values: DUPLICATED_CHARGE, PRODUCT_UNSATISFACTORY, ORDER_CHANGE, ORDER_CANCELLATION, FRAUDULENT_CHARGE, OTHER
description
string		Provide a description of the credit note for internal reference.
credit_amount
object		Set the total amount to credit to the customer balance for future use. Only include value field (currency is inherited from invoice).
refund_amount
object		Set the total amount to refund to the customer immediately. Only include value field (currency is inherited from invoice).
items
Required, array		Provide an array of credit note items specifying which fees to credit or refund. Minimum 1 item required.
items[].fee_id
Required, string		Set to the fee identifier from the original invoice.
items[].amount
Required, object		Set the amount for this credit note item. Only include value field.
For information on all parameters, see API reference. 
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
          }
        }
      ]
    }'
A successful call returns a 201 Created response. The response includes the following parameters:
ParameterDescriptionFurther action
id
string		Unique identifier for the credit note.Use this id when getting credit note details or voiding the credit note.
credit_status
string		Status of the credit amount.

Possible values: AVAILABLE, CONSUMED, VOIDED.		Use this credit_status to filter credit notes.
refund_status
string		Status of the refund amount.

Possible values: PENDING, SUCCEEDED, FAILED.		Use this refund_status to filter credit notes.
For information on all parameters, see API reference.

​
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.