> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage credit notes

<div className="m-badge-page-wrapper">
  <Badge stroke color="orange" size="sm">Limited Release</Badge>
</div>

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 <a href="/developer/how-to/api/get-started#2-get-an-access-token" target="_blank" rel="noopener noreferrer">valid access token</a> and make a GET call to the `/v1/commerce/billing/credit-notes` endpoint. Include the following query parameters:

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>                            | <span style={{textAlign: 'left', display: 'block'}}>Action</span>                                                                                                                                                                                   |
| ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `page`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>integer</span>                | Set the page number for paginated results. Default is `1`.                                                                                                                                                                                          |
| `per_page`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>integer</span>            | Set the number of credit notes to return per page. Default is `10`, maximum is `100`.                                                                                                                                                               |
| `status`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>               | Filter credit notes by status.<br /><br /><b>Possible values:</b> `DRAFT`, `FINALIZED`, `VOIDED`                                                                                                                                                    |
| `credit_status`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>        | Filter credit notes by credit status.<br /><br /><b>Possible values:</b> `AVAILABLE`, `CONSUMED`, `VOIDED`                                                                                                                                          |
| `refund_status`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>        | Filter credit notes by refund status.<br /><br /><b>Possible values:</b> `PENDING`, `SUCCEEDED`, `FAILED`                                                                                                                                           |
| `reason`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>               | Filter credit notes by reason.<br /><br /><b>Possible values:</b> `DUPLICATED_CHARGE`, `PRODUCT_UNSATISFACTORY`, `ORDER_CHANGE`, `ORDER_CANCELLATION`, `FRAUDULENT_CHARGE`, `OTHER`                                                                 |
| `issuing_date_from`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>    | Set the start date to filter credit notes issued from this date (YYYY-MM-DD format).                                                                                                                                                                |
| `issuing_date_to`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>      | Set the end date to filter credit notes issued until this date (YYYY-MM-DD format).                                                                                                                                                                 |
| `external_customer_id`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span> | Set to the `external_id` returned when you <a href="/limited-release/usage-based-billing/set-up-billing-process/register-customers" target="_blank" rel="noopener noreferrer">registered the customer</a> to filter credit notes for that customer. |
| `invoice_id`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>           | Set to the `id` returned when you <a href="/limited-release/usage-based-billing/meter-bill/generate-invoices" target="_blank" rel="noopener noreferrer">listed the invoices</a> to filter credit notes for that invoice.                            |

For information on all parameters, see <a href="/reference/api/rest/credit-notes/get-all-credit-notes" target="_blank" rel="noopener noreferrer">API reference</a>.

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  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>'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
    "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
    }
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response with a paginated list of credit notes.

## Get credit note details

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token" target="_blank" rel="noopener noreferrer">valid access token</a> 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](#list-credit-notes) response.

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  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>'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
    "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"
  }
  ```
</CodeGroup>

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

## Void credit notes

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token" target="_blank" rel="noopener noreferrer">valid access token</a> 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](#list-credit-notes) response.

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  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>'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
    "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"
  }
  ```
</CodeGroup>

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