Preview a subscription's next invoice

Shows the invoice a subscription's next renewal will issue, computed by the renewal's own code in a transaction that is rolled back: licensed items for the next period (after a change scheduled for then), metered usage of the ending period so far, late usage, pending invoice items, discounts, tax at the rates known today and the customer's credit balance. It has no number (number: null) and nothing is kept.

For a trial it is the first invoice; for a subscription set to cancel, its final invoice (usage and pending items). A subscription that bills nothing next (ended, paused without invoices, unpaid, or nothing to bill) returns invoice_upcoming_none. Usage recorded until the period end still changes the real invoice.

At a glance

REST: GET /api/v1/invoices/upcoming
MCP tool: invoices_upcoming
Operation ID: invoices.upcoming
Scope: Brand
Permission: invoices:read
Risk tier: read
Dry run: Not supported
Idempotency: Not needed (read only)
Modes: Test and live
Authentication: API key with the invoices:read scope
Since: M5

Request

Query parameters

Field	Type	Required	Description
`subscriptionId`	`sub_…` ID	Yes	The subscription whose next invoice to preview (`sub_…`).

Response

200 OK with a JSON object:

Field	Type	Description
`id`	`inv_…` ID
`object`	`"invoice"`
`livemode`	boolean
`entityId`	`ent_…` ID
`brandId`	`brd_…` ID
`number`	string or null	The invoice number: gap-free per legal entity, mode, brand series and year (§18.2). Null for a draft: the number is taken at finalization.
`numbering`	object or null
`customerId`	`cus_…` ID or null
`subscriptionId`	`sub_…` ID or null
`collectionMethod`	one of `charge_automatically`, `send_invoice`
`kind`	one of `invoice`, `receipt` or null	`invoice` (business customers) or `receipt` (the receipt-invoice consumers get); null for a draft.
`status`	one of 9 values, e.g. `draft`, `pending_registration`, `issued` (all in the OpenAPI document)	`draft` → `open` (finalized) → `paid`, `void` or `uncollectible`. Checkout invoices are `issued` (paid at once), or `pending_registration`: a full invoice charged before the tax registration exists; the receipt went out and the formal invoice follows (§18.1).
`language`	one of `en`, `de`, `fr`, `hr`, `it`, `es` or null
`issuedAt`	date-time or null
`issueDate`	string or null	The issue date in the seller's time zone.
`taxPoint`	date-time or null
`taxPointDate`	string or null	The date of supply in the seller's time zone.
`daysUntilDue`	integer or null	send_invoice: days from the issue date to the due date.
`dueDate`	string or null	send_invoice: when payment is due (fixed at finalization).
`seller`	object or null
`buyer`	object or null
`currency`	string
`lines`	array of object
`lines[].id`	string	The tax quote's line ID.
`lines[].description`	string
`lines[].productId`	`prod_…` ID or null
`lines[].priceId`	`price_…` ID or null
`lines[].quantity`	integer
`lines[].taxCategoryId`	one of 9 values, e.g. `electronically_supplied_service`, `saas`, `ebook` (all in the OpenAPI document)
`lines[].taxBehavior`	one of `inclusive`, `exclusive`
`lines[].unitAmount`	money	The net price of one unit (may be finer than the minor unit).
`lines[].net`	money
`lines[].tax`	object
`lines[].tax.ratePpm`	string	Parts per million as a string (19% = "190000").
`lines[].tax.amount`	money
`lines[].tax.jurisdictionId`	string or null
`lines[].tax.regimeId`	string or null
`lines[].tax.decision`	one of `charge`, `reverse_charge`, `exempt`, `not_taxable`, `out_of_scope`, `not_collected`, `blocked`	What happened to the tax: `charge`, `reverse_charge`, `exempt`, `not_taxable`, `out_of_scope`, `not_collected`.
`lines[].tax.rateKind`	one of `standard`, `reduced`, `super_reduced`, `parking`, `zero`, `exempt`, `not_taxable` or null
`lines[].tax.rateId`	string or null
`lines[].tax.pendingRegistration`	boolean
`lines[].gross`	money
`lines[].kind`	one of `licensed`, `metered`, `late_usage`, `proration`, `invoice_item` or null	Where the line came from (§16.3 order); null on checkout invoices.
`lines[].period`	object or null
`lines[].subscriptionItemId`	string or null
`lines[].invoiceItemId`	`ii_…` ID or null
`lines[].discount`	money or null	What discounts took off the line before tax.
`lines[].meteredQuantity`	string or null	A metered line's usage (its quantity is 1).
`totals`	object or null
`taxCurrencyTotals`	object or null	The tax in the seller's tax currency when the invoice is in another one (§18.3).
`creditApplied`	money or null	Taken from the customer's credit balance at finalization (§16.11).
`amountDue`	money or null	What the customer pays: the gross total less the credit applied. Null on checkout invoices.
`notes`	array of object
`notes[].code`	one of `reverse_charge`, `exempt`, `out_of_scope`, `registration_pending`, `oss_scheme`
`notes[].text`	string	The note as printed.
`fieldCheck`	object or null	What the knowledge base's invoicing rules ask for that the invoice lacks (`missing`), and requirements Ownrecord can't check yet (`unchecked`).
`pendingRegistration`	boolean	A full invoice with a line charged before the registration exists (§18.1).
`paymentIds`	array of `pay_…` ID
`creditNoteIds`	array of `cn_…` ID
`ledgerTxnIds`	array of `txn_…` ID
`quoteId`	`tq_…` ID or null	The tax quote the invoice shows (null for a draft).
`quoteIds`	array of `tq_…` ID	Every quote of the invoice: lines taxed at another date (prorations) have their own quote.
`pdf`	object or null	Null for a draft: the PDF is rendered at finalization.
`finalizedAt`	date-time or null
`paidAt`	date-time or null
`payment`	object or null	How the invoice was paid: `bank_transfer` (marked paid), `processor` (a card or debit payment) or `credit_balance`.
`voidedAt`	date-time or null
`markedUncollectibleAt`	date-time or null
`emailedAt`	date-time or null
`sentAt`	date-time or null	When `invoices.send` last emailed the invoice.
`draft`	object or null	A draft's lines before tax (tax is quoted at finalization); null once finalized.
`metadata`	object
`version`	integer	Pass it as `expectedVersion` to refuse a change if the invoice changed. Rendering the PDF and emailing the invoice change it too.
`createdAt`	date-time
`updatedAt`	date-time

Examples

The next renewal of a monthly subscription with metered usage

HTTP

GET /api/v1/invoices/upcoming?subscriptionId=sub_01jacq4m3xf0v8w9zq2y7k5n6s
Authorization: Bearer or_test_…

Response (200):

JSON

{
  "id": "inv_01m4tx5nj8emwbyf7y9vcf47yk",
  "object": "invoice",
  "livemode": false,
  "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "number": null,
  "numbering": null,
  "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47ym",
  "subscriptionId": "sub_01jacq4m3xf0v8w9zq2y7k5n6s",
  "collectionMethod": "charge_automatically",
  "kind": "invoice",
  "status": "open",
  "language": "en",
  "issuedAt": "2026-11-20T10:00:00.000Z",
  "issueDate": "2026-11-20",
  "taxPoint": "2026-11-20T10:00:00.000Z",
  "taxPointDate": "2026-11-20",
  "daysUntilDue": 14,
  "dueDate": null,
  "seller": {
    "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
    "legalName": "Acme Digital d.o.o.",
    "tradingName": null,
    "address": {
      "line1": "Ilica 1",
      "line2": null,
      "city": "Zagreb",
      "postalCode": "10000",
      "region": null,
      "country": "HR"
    },
    "companyRegistryId": "080000001",
    "taxIds": [
      {
        "type": "eu_vat",
        "value": "HR12345678901",
        "regimeId": null
      }
    ],
    "brand": {
      "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
      "name": "Genno",
      "primaryColor": "#0E6B5C",
      "accentColor": null,
      "supportEmail": "help@genno.example",
      "supportUrl": null
    },
    "footerText": null
  },
  "buyer": {
    "type": "b2b",
    "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47ym",
    "name": "Alpen Apps GmbH",
    "email": "billing@alpen.example",
    "address": null,
    "country": "AT",
    "taxId": {
      "type": "eu_vat",
      "value": "ATU00000000",
      "country": "AT"
    }
  },
  "currency": "EUR",
  "lines": [
    {
      "id": "1",
      "description": "App (Pro)",
      "productId": "prod_01jacq4m3xf0v8w9zq2y7k5n6p",
      "priceId": "price_01jacq4m3xf0v8w9zq2y7k5n6p",
      "quantity": 3,
      "taxCategoryId": "saas",
      "taxBehavior": "exclusive",
      "unitAmount": {
        "amount": "30000000",
        "currency": "EUR"
      },
      "net": {
        "amount": "90000000",
        "currency": "EUR"
      },
      "tax": {
        "ratePpm": "0",
        "amount": {
          "amount": "0",
          "currency": "EUR"
        },
        "jurisdictionId": "AT",
        "regimeId": "EU_OSS_UNION",
        "decision": "reverse_charge",
        "rateKind": null,
        "rateId": null,
        "pendingRegistration": false
      },
      "gross": {
        "amount": "90000000",
        "currency": "EUR"
      },
      "kind": "licensed",
      "period": {
        "start": "2026-11-20T10:00:00.000Z",
        "end": "2026-12-20T10:00:00.000Z"
      },
      "subscriptionItemId": "si_01jacq4m3xf0v8w9zq2y7k5n6i",
      "invoiceItemId": null,
      "discount": null,
      "meteredQuantity": null
    },
    {
      "id": "2",
      "description": "API",
      "productId": "prod_01jacq4m3xf0v8w9zq2y7k5n6a",
      "priceId": "price_01jacq4m3xf0v8w9zq2y7k5n6a",
      "quantity": 1,
      "taxCategoryId": "saas",
      "taxBehavior": "exclusive",
      "unitAmount": {
        "amount": "12500000",
        "currency": "EUR"
      },
      "net": {
        "amount": "12500000",
        "currency": "EUR"
      },
      "tax": {
        "ratePpm": "0",
        "amount": {
          "amount": "0",
          "currency": "EUR"
        },
        "jurisdictionId": "AT",
        "regimeId": "EU_OSS_UNION",
        "decision": "reverse_charge",
        "rateKind": null,
        "rateId": null,
        "pendingRegistration": false
      },
      "gross": {
        "amount": "12500000",
        "currency": "EUR"
      },
      "kind": "metered",
      "period": {
        "start": "2026-10-20T09:00:00.000Z",
        "end": "2026-11-20T10:00:00.000Z"
      },
      "subscriptionItemId": "si_01jacq4m3xf0v8w9zq2y7k5n6m",
      "invoiceItemId": null,
      "discount": null,
      "meteredQuantity": "1250"
    }
  ],
  "totals": {
    "net": {
      "amount": "102500000",
      "currency": "EUR"
    },
    "tax": {
      "amount": "0",
      "currency": "EUR"
    },
    "gross": {
      "amount": "102500000",
      "currency": "EUR"
    },
    "taxByRate": [
      {
        "ratePpm": "0",
        "jurisdictionId": "AT",
        "regimeId": "EU_OSS_UNION",
        "decision": "reverse_charge",
        "net": {
          "amount": "102500000",
          "currency": "EUR"
        },
        "tax": {
          "amount": "0",
          "currency": "EUR"
        }
      }
    ]
  },
  "taxCurrencyTotals": null,
  "creditApplied": null,
  "amountDue": {
    "amount": "102500000",
    "currency": "EUR"
  },
  "notes": [
    {
      "code": "reverse_charge",
      "text": "Prijenos porezne obveze (reverse charge) – čl. 17. st. 1. Zakona o PDV-u"
    }
  ],
  "fieldCheck": {
    "invoicingRuleIds": [],
    "missing": ["buyer_address"],
    "unchecked": []
  },
  "pendingRegistration": false,
  "paymentIds": [],
  "creditNoteIds": [],
  "ledgerTxnIds": ["txn_01m4tx5nj8emwbyf7y9vcf47yn"],
  "quoteId": "tq_01m4tx5nj8emwbyf7y9vcf47xr",
  "quoteIds": ["tq_01m4tx5nj8emwbyf7y9vcf47xr"],
  "pdf": {
    "status": "pending",
    "fileId": null,
    "sha256": null,
    "size": null,
    "templateVersion": null,
    "renderedAt": null,
    "url": "/api/v1/invoices/inv_01m4tx5nj8emwbyf7y9vcf47yk/pdf"
  },
  "finalizedAt": "2026-10-20T09:00:00.000Z",
  "paidAt": null,
  "payment": null,
  "voidedAt": null,
  "markedUncollectibleAt": null,
  "emailedAt": null,
  "sentAt": null,
  "draft": null,
  "metadata": {
    "contract": "ENT-2026-07"
  },
  "version": 2,
  "createdAt": "2026-10-20T08:30:00.000Z",
  "updatedAt": "2026-10-20T09:00:00.000Z"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	`subscriptionId` is missing or malformed.	Fix the fields listed in `details.issues` and send the request again.
`resource_not_found`	404	No subscription with this ID exists for the brand in this mode.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`invoice_upcoming_none`	404	Nothing is billed at the next period end: ended, set to end with nothing to bill, paused without invoices, or unpaid (`details.reason`).	Nothing is billed at the next period end: the subscription has ended, is set to end without anything left to bill, is paused without invoices, or is unpaid. Read the subscription for its status.
`registration_required`	422	The invoice couldn't be taxed now: the seller isn't registered where the customer is.	Register the entity for the regime named in `details.regime` (see its prerequisites and deadline), or arm the jurisdiction once the prerequisites are done. The customer can join the waitlist meanwhile.
`jurisdiction_blocked`	422	The customer's location is blocked.	This jurisdiction isn't covered by usable tax knowledge for this seller. Contact support if you need to sell there.
`evidence_conflict`	422	The customer's stored location evidence isn't enough to tax the invoice (§13.3).	Collect another piece of location evidence (billing address, card country, or the customer's confirmation of their country) and quote again.
`permission_denied`	403	The credentials can't read this brand's invoices (`invoices:read`).	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, authentication_required, api_key_invalid, scope_required, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Query parameters#

Response#

Examples#

The next renewal of a monthly subscription with metered usage#

Errors#