Skip to main content
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. 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.
The response lists the invoices in order of invoice moment, earliest first. Each invoice has its charges in lineItems.
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

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