Manage credit notes - Paypal Docs

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:

Parameter	Action
`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>'

{
  "credit_notes": [
    {
      "id": "cn_01H2XT1G7N8E2JHJKBVPDS0TQD",
      "billing_entity_code": "lex_corp",
      "sequential_id": 3,
      "number": "CN-2023-0001",
      "invoice_id": "inv_01H2XT1G7N8E2JHJKBVPDS0TQD",
      "invoice_number": "INV-2023-001",
      "issuing_date": "2023-06-01",
      "credit_status": "AVAILABLE",
      "refund_status": "SUCCEEDED",
      "reason": "ORDER_CANCELLATION",
      "description": "Refund for cancelled subscription",
      "total_amount": {
        "value": 50,
        "currency_code": "USD"
      },
      "credit_amount": {
        "value": 25,
        "currency_code": "USD"
      },
      "refund_amount": {
        "value": 25,
        "currency_code": "USD"
      },
      "balance_amount": {
        "value": 25,
        "currency_code": "USD"
      },
      "taxes_amount": {
        "value": 0,
        "currency_code": "USD"
      },
      "taxes_rate": 0.2,
      "sub_total_excluding_taxes_amount": {
        "value": 0,
        "currency_code": "USD"
      },
      "created_at": "2023-05-10T14:32:18Z",
      "updated_at": "2023-05-10T14:32:18Z"
    }
  ],
  "metadata": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1
  }
}

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>'

{
  "id": "cn_01H2XT1G7N8E2JHJKBVPDS0TQD",
  "billing_entity_code": "lex_corp",
  "sequential_id": 3,
  "number": "CN-2023-0001",
  "invoice_id": "inv_01H2XT1G7N8E2JHJKBVPDS0TQD",
  "invoice_number": "INV-2023-001",
  "issuing_date": "2023-06-01",
  "credit_status": "AVAILABLE",
  "refund_status": "SUCCEEDED",
  "reason": "ORDER_CANCELLATION",
  "description": "Refund for cancelled subscription",
  "total_amount": {
    "value": 50,
    "currency_code": "USD"
  },
  "credit_amount": {
    "value": 25,
    "currency_code": "USD"
  },
  "refund_amount": {
    "value": 25,
    "currency_code": "USD"
  },
  "balance_amount": {
    "value": 25,
    "currency_code": "USD"
  },
  "taxes_amount": {
    "value": 0,
    "currency_code": "USD"
  },
  "taxes_rate": 0.2,
  "sub_total_excluding_taxes_amount": {
    "value": 0,
    "currency_code": "USD"
  },
  "created_at": "2023-05-10T14:32:18Z",
  "updated_at": "2023-05-10T14:32:18Z"
}

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>'

{
  "id": "cn_01H2XT1G7N8E2JHJKBVPDS0TQD",
  "sequential_id": 3,
  "billing_entity_code": "lex_corp",
  "number": "CN-2023-0001",
  "invoice_id": "inv_01H2XT1G7N8E2JHJKBVPDS0TQD",
  "invoice_number": "INV-2023-001",
  "issuing_date": "2023-06-01",
  "credit_status": "VOIDED",
  "refund_status": "SUCCEEDED",
  "reason": "ORDER_CANCELLATION",
  "description": "Refund for cancelled subscription",
  "total_amount": {
    "value": 50,
    "currency_code": "USD"
  },
  "credit_amount": {
    "value": 0,
    "currency_code": "USD"
  },
  "refund_amount": {
    "value": 0,
    "currency_code": "USD"
  },
  "balance_amount": {
    "value": 0,
    "currency_code": "USD"
  },
  "taxes_amount": {
    "value": 0,
    "currency_code": "USD"
  },
  "sub_total_excluding_taxes_amount": {
    "value": 0,
    "currency_code": "USD"
  },
  "taxes_rate": 0.2,
  "created_at": "2023-05-10T14:32:18Z",
  "updated_at": "2023-06-15T10:45:22Z"
}

A successful call returns a 200 OK response with the voided credit note details.

​List credit notes

​Get credit note details

​Void credit notes

List credit notes

Get credit note details

Void credit notes