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

# Invoices

> Learn what each invoice status means and how to track invoices with the API and webhooks.

Paygentic issues an invoice at the end of each billing period for every active subscription. The invoice lists the charges for the period, including usage and tax. Paygentic then collects payment from the customer.

You don't create subscription invoices yourself. You track their status, and act when a payment fails.

Invoice 0, the first invoice of a subscription, works differently. Paygentic issues it when you create the subscription. See [The first invoice](/platform/billing/subscriptions#the-first-invoice).

## Invoice statuses

| Status | Description |
| - | - |
| `ACTIVE` | The billing period is still open. Charges are added as they happen. |
| `ISSUED` | The invoice was sent to the customer and is waiting for payment. It stays `ISSUED` while Paygentic retries a failed charge. |
| `PAYMENT_FAILED` | Paygentic stopped retrying a failed charge. The customer can still pay the invoice. See [When an automatic charge fails](/platform/billing/subscriptions#when-an-automatic-charge-fails). |
| `PAID` | The invoice is paid. This status is final. |
| `CANCELLED` | The invoice was cancelled, and nothing is owed. This status is final. |
| `WRITTEN_OFF` | The invoice was written off as unpaid. This status is final. |

After a billing period ends, Paygentic calculates the final amount before it issues the invoice. During this short time, the API can return `CLOSING`, `CLOSED`, `CALCULATING`, or `DRAFT`. You don't need to do anything with these statuses.

If Paygentic can't prepare an invoice, its status is `FAILED`. Contact [support@paygentic.io](mailto:support@paygentic.io) if you see this status.

If an invoice total is zero, Paygentic marks it `PAID` when it's issued.

## Pay an invoice

How the customer pays depends on the subscription's `autoCharge` setting. See [How invoices are paid](/platform/billing/subscriptions#how-invoices-are-paid).

While an invoice is unpaid, its `paymentUrl` field links to the invoice payment page. You can use this link in your own app or emails.

## Track invoices

To list invoices, use `GET /v2/invoices`. You can filter by `subscriptionId`, `customerId`, or `status`. To get a single invoice, use `GET /v2/invoices/{id}`, and to download its PDF, use `GET /v2/invoices/{id}/pdf`.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.paygentic.io/v2/invoices?customerId=cus_p1q2r3s4t5u6v7w8&status=ISSUED" \
    -H "Authorization: Bearer sk_test_YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.paygentic.io/v2/invoices?customerId=cus_p1q2r3s4t5u6v7w8&status=ISSUED',
    { headers: { 'Authorization': 'Bearer sk_test_YOUR_API_KEY' } }
  );

  const { data: invoices } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.paygentic.io/v2/invoices",
      params={"customerId": "cus_p1q2r3s4t5u6v7w8", "status": "ISSUED"},
      headers={"Authorization": "Bearer sk_test_YOUR_API_KEY"},
  )

  invoices = response.json()["data"]
  ```
</CodeGroup>

Paygentic sends the `invoice.issued.v0` webhook when an invoice is issued, and `invoice.paid.v0` when it's paid. It doesn't send a webhook when an invoice changes to `PAYMENT_FAILED`, `CANCELLED`, or `WRITTEN_OFF`. To find those invoices, filter by `status`.

For event payloads and delivery details, see [Webhooks](/platform/developers/webhooks#event-types-reference).

<Info>
  **API Reference**: See the [List Invoices](/api-reference/invoices-v2/list) and [Get Invoice](/api-reference/invoices-v2/get) endpoints for all fields and filters.
</Info>

## Next steps

* [Subscriptions](/platform/billing/subscriptions)
* [Customer emails](/platform/billing/customer-emails)
* [Webhooks](/platform/developers/webhooks)