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

# Generate invoices

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

An invoice is a billing document that charges customers for their usage during a billing period. PayPal's Usage-based Billing automatically creates these invoices when billing periods end or when subscriptions are cancelled. You can:

* [List invoices](#list-invoices) to manage your billing operations:
  * View all invoices with filters and create customer dashboards to track payment history.
  * Reconcile billing data with your internal systems for accurate record keeping.
* [Get the invoice details of a specific customer](#get-invoice-details) and display invoice information to the customer.

## List invoices

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/invoices` 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'}}>string</span>                                                                                 | Set the page number for paginated results.                                                                                                                                                                                                      |
| `per_page`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                             | Set the number of invoices to return per page.                                                                                                                                                                                                  |
| `issuing_date_from`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span> | Set the start date to filter invoices issued on or after this date (YYYY-MM-DD).                                                                                                                                                                |
| `issuing_date_to`<br /><span style={{color: 'red', fontSize: 'smaller'}}>Required</span>, <span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>   | Set the end date to filter invoices issued on or before this date (YYYY-MM-DD).                                                                                                                                                                 |
| `status`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                               | Filter invoices by status.<br /><br /><b>Possible values:</b> `DRAFT`, `FINALIZED`                                                                                                                                                              |
| `payment_status`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span>                                                                       | Filter invoices by payment status.<br /><br /><b>Possible values:</b> `PENDING`, `FAILED`, `SUCCEEDED`                                                                                                                                          |
| `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 invoices for that customer. |

For information on all parameters, see <a href="/reference/api/rest/invoices/get-all-invoices" 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/invoices?page=1&per_page=20&issuing_date_from=2022-07-08&issuing_date_to=2025-07-29&status=FINALIZED&external_customer_id=5eb02857-a71e-4ea2-bcf9-1752555395' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer <ACCESS-TOKEN>'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
    "invoices": [
      {
        "id": "27986ceb-bb27-461d-82b1-f044646e192d",
        "sequential_id": 5,
        "status": "FINALIZED",
        "payment_status": "PENDING",
        "amount": {
          "total_amount": {
            "value": 220.2,
            "currency_code": "USD"
          }
        },
        "due_date": "2025-07-28",
        "issued_date": "2025-07-28",
        "invoice_number": "PPC-9E32-202507-012",
        "version_number": "4",
        "payment_overdue": true,
        "invoice_type": "SUBSCRIPTION",
        "customer": {
          "name": "Test Plan Override Customer",
          "external_id": "5eb02857-a71e-4ea2-bcf9-1752555395",
          "email": "finance@techstart.io",
          "address": {
            "line1": "123 Innovation Way",
            "line2": "Suite 400",
            "city": "San Francisco",
            "state": "CA",
            "country": "US"
          },
          "phone": "+1 (555) 789-1234",
          "id": "5a31b634-3213-42f5-a184-c68f93e47dc1"
        },
        "created_at": "2025-07-28T00:10:01Z",
        "updated_at": "2025-07-29T00:25:00Z"
      },
      {
        "id": "9cf09b3f-9e52-434c-b3f4-3675739795fa",
        "sequential_id": 3,
        "status": "FINALIZED",
        "payment_status": "PENDING",
        "amount": {
          "total_amount": {
            "value": 500.11,
            "currency_code": "USD"
          }
        },
        "due_date": "2025-07-28",
        "issued_date": "2025-07-28",
        "invoice_number": "PPC-9E32-202507-003",
        "version_number": "4",
        "payment_overdue": true,
        "invoice_type": "SUBSCRIPTION",
        "customer": {
          "name": "CUST_NLT_1752783445",
          "external_id": "5eb02857-a71e-4ea2-bcf9-1752783445",
          "email": "sakdjas@comp.net",
          "id": "6610c88a-bde2-4f62-bce5-02a29384cfc3"
        },
        "created_at": "2025-07-28T00:10:01Z",
        "updated_at": "2025-07-29T00:25:02Z"
      }
    ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response. The response includes the following parameter:

| <span style={{textAlign: 'left', display: 'block'}}>Parameter</span>          | <span style={{textAlign: 'left', display: 'block'}}>Description</span> | <span style={{textAlign: 'left', display: 'block'}}>Further action</span>         |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `id`<br /><span style={{color: '#95a5a6', fontSize: 'smaller'}}>string</span> | Unique identifier for the invoice.                                     | Use this `id` when <a href="#get-invoice-details">retrieving invoice details</a>. |

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

## Get invoice 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/invoices/{invoice_id}` endpoint.

**Path parameter**: `invoice_id` is the `id` returned in the <a href="#list-invoices">List invoices</a> response.

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X GET 'https://api-m.sandbox.paypal.com/v1/commerce/billing/invoices/9cf09b3f-9e52-434c-b3f4-3675739795fa' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer <ACCESS-TOKEN>'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
        "id": "9cf09b3f-9e52-434c-b3f4-3675739795fa",
        "sequential_id": 3,
        "status": "FINALIZED",
        "payment_status": "PENDING",
        "payment_overdue": true,
        "invoice_type": "SUBSCRIPTION",
        "invoice_number": "PPC-9E32-202507-003",
        "version_number": 4,
        "billing_entity_code": "US_ENTITY",
        "amount": {
          "total_amount": {
            "value": 500.11,
            "currency_code": "USD"
          }
        },
        "fees": [
          {
            "id": "f3c91be7-85ba-4f41-857b-f844749e4f1b",
            "total_amount": {
              "value": 500.00,
              "currency_code": "USD"
            }
          },
          {
            "id": "e58684ef-8e26-4339-a2ba-b243beffc3f1",
            "total_amount": {
              "value": 0.11,
              "currency_code": "USD"
            }
          }
        ],
        "applied_taxes": [
          {
            "tax_name": "State Tax",
            "tax_amount": {
              "value": 45.46,
              "currency_code": "USD"
            },
            "tax_rate": 10.0
          }
        ],
        "billing_period": [
          {
            "subscription_id": "sub_02H3YT8P7Q5R3S1T2U0V4W9X9",
            "external_subscription_id": "ext_sub_67890",
            "plan_id": "plan_02H3YT8P7Q5R3S1T2U0V4W9X9",
            "payment_method_token": "pm_visa_5555",
            "payment_method_type": "CARD",
            "subscription_from_datetime": "2025-07-01T00:00:00Z",
            "subscription_to_datetime": "2025-07-31T23:59:59Z",
            "charges_from_datetime": "2025-07-01T00:00:00Z",
            "charges_to_datetime": "2025-07-31T23:59:59Z",
            "invoicing_reason": "subscription"
          }
        ],
        "due_date": "2025-07-28",
        "issued_date": "2025-07-28",
        "customer": {
          "id": "6610c88a-bde2-4f62-bce5-02a29384cfc3",
          "external_id": "5eb02857-a71e-4ea2-bcf9-1752783445",
          "name": "Sarah Johnson",
          "email": "sarah.johnson@company.com",
          "phone": "+1 (555) 123-4567",
          "address": {
            "line1": "456 Business Ave",
            "line2": "Floor 2",
            "city": "Austin",
            "state": "TX",
            "country": "US"
          }
        },
        "created_at": "2025-07-28T00:10:01Z",
        "updated_at": "2025-07-29T00:25:02Z"
      }
  ```
</CodeGroup>

A successful call returns a `200 OK` response with detailed invoice information. You can send or show the invoice information in the appropriate format to your customer.

{/***Use this endpoint when:***/}

{/*- Your automated dunning process triggers a retry attempt*/}

{/*- Temporary payment method issues are resolved (for example, insufficient funds now available)*/}

{/*<Tabs>*/}

{/*    ```bash*/}

{/*    -H 'Content-Type: application/json' \*/}

{/*    ```*/}

{/*  <TabItem value="response" label="Response">*/}

{/*    204 No Content*/}

{/*  </TabItem>*/}

{/*### Response parameters*/}