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

# Projected invoices

> Preview the invoices a subscription will issue in the future, with estimated totals, tax and sequence numbers.

A projected invoice is an invoice that your subscription's schedule says Paygentic will issue at a future invoice moment. You can use it to show a customer what they will be charged next, or to check your pricing before a billing period starts.

Paygentic derives projected invoices on each request and never stores them. A request can bring the subscription's schedule up to date with its plan, as the next billing run would. A projected invoice has the status `PROJECTED`. You cannot approve, pay or download it.

Each projected invoice has an `id` that stays the same between requests. You can't fetch it by id, though. `GET /v2/invoices/{id}` returns `404` for a projected invoice.

## Request projected invoices

Call `GET /v2/invoices/projected` with the `subscriptionId`. Use `from` and `to` to filter on the invoice moment. Use `limit` and `offset` to page through the results.

| Parameter | Description |
| - | - |
| `subscriptionId` | Required. The subscription to project invoices for. |
| `from` | The start of the range, inclusive. Defaults to now. If it is in the past, Paygentic uses now. |
| `to` | The end of the range, exclusive. Defaults to one month after `from`. It can be at most one year ahead. |
| `limit`, `offset` | Pagination. `limit` defaults to 10. |

If the subscription has a test clock, "now" is the test-clock time. For the full list of parameters and responses, see the [List projected invoices](/api-reference/invoices-v2/list-projected) API reference.

```bash theme={null}
curl "https://api.paygentic.io/v2/invoices/projected?subscriptionId=sub_abc123&to=2026-12-01T00:00:00Z" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

The response lists the invoices in order of invoice moment, earliest first. Each invoice has its charges in `lineItems`.

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "inv_proj_8f2c1d9a",
      "object": "invoice",
      "merchantId": "mer_abc123",
      "subscriptionId": "sub_abc123",
      "customerId": "cus_abc123",
      "status": "PROJECTED",
      "sequenceNumber": 3,
      "currency": "USD",
      "periodStart": "2026-11-01T00:00:00.000Z",
      "periodEnd": "2026-12-01T00:00:00.000Z",
      "subtotal": "100.00",
      "totalTax": "20.00",
      "grandTotal": "120.00",
      "lineItems": {
        "invoiceId": "inv_proj_8f2c1d9a",
        "lineItems": [
          {
            "eventType": "fee",
            "lineItemType": "charge",
            "invoiceDisplayName": "Platform fee",
            "quantity": 1,
            "unitPrice": "100.00",
            "totalPrice": "100.00",
            "taxRate": 0.2,
            "totalTax": "20.00",
            "totalAmount": "120.00",
            "periodStart": "2026-11-01T00:00:00.000Z",
            "periodEnd": "2026-12-01T00:00:00.000Z",
            "paymentTerm": "in_advance"
          }
        ],
        "nextPageToken": null,
        "totalCount": 1
      }
    }
  ],
  "pagination": { "limit": 10, "offset": 0, "total": 1 }
}
```

The example shows a trimmed response. The real response has every field of the invoice and line item schemas.

## What a projected invoice includes

Paygentic returns one projected invoice for each invoice moment. Charges that fall due at the same moment are on the same invoice. A charge with its own billing cadence can fall due at a different moment, and so it is on a different invoice.

A projected invoice includes:

* Fee charges from the subscription's timeline, including future changes that are already scheduled.
* Manual line items that no invoice has claimed yet.
* Percentage discounts, and quantity minimums and maximums, as Paygentic applies them when it closes the invoice.

## Limits

<Warning>
  Projected totals exclude usage. Paygentic does not project metered charges, usage discounts or grant discounts, and it does not return an invoice moment that has only metered charges. The real invoice can be higher or lower than the projected one.
</Warning>

<Note>
  Tax, `sequenceNumber` and `dueAt` are estimates. The real invoice can have different values. For example, an invoice that waits for a manual approval is due from the day it is approved.
</Note>

A terminated subscription returns an empty list.

## How tax is estimated

Paygentic does not ask the tax authority for a projected invoice. It estimates the tax rate of each charge with the first of these rates that it finds:

1. The rate of the latest issued invoice on the same subscription that has the same charge.
2. The rate of the latest issued invoice for the same customer that has the same item.
3. The default tax rate of the plan.

Paygentic uses rates 1 and 2 only if you have connected a tax account. Without one, your invoices use the plan's default tax rate, so the projection uses it too.

If the subscription is tax exempt, the tax is `0`. A charge that is out of scope for tax gets no tax. A discount or a credit reduces the amount that the rate applies to, and the discount line has no tax of its own.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.