---
title: "The next invoice"
description: "What Stripe will charge at the next renewal: the plan, every add-on pack at its quantity, prorations still to bill, tax."
canonical: "https://grid82.com/docs/builder-api/billing/upcoming"
updated: "2026-11-20"
---

# The next invoice

`GET https://studio.grid82.app/v1/organizations/{organizationId}/billing/upcoming`

What Stripe will charge at the next renewal: the plan, every add-on pack at its quantity, prorations still to bill, tax.

`null` with no paid subscription, or when Stripe cannot be reached.

Requires the `account:read` scope. Operation `billing.upcoming`. Not an MCP tool. Asks Stripe on every call. An agent reads the plan, its limits and the packs with billing.get. CLI: `grid82 billing upcoming` (`npx @grid82/cli`).

## Path parameters

| Name             | Type   | Required | Description |
| ---------------- | ------ | -------- | ----------- |
| `organizationId` | string | yes      |             |

**Authorizations**

- `Authorization` (bearer, in header, required)

## Response

**200**: Success

- `data` (`object | null`, required)
- `data.amountDue` (`number`, required)
- `data.currency` (`string`, required)
- `data.at` (`string,null`, required)
- `data.lines` (`object[]`, required)
- `data.lines.description` (`string`, required)
- `data.lines.amount` (`number`, required)
- `data.lines.quantity` (`number,null`, required)

```json
{
  "data": {
    "amountDue": 123.45,
    "currency": "<string>",
    "at": null,
    "lines": [
      {
        "description": "<string>",
        "amount": 123.45,
        "quantity": null
      }
    ]
  }
}
```

**4XX**: Refused

- `error` (`object`, required)
- `error.code` (`enum<string>`, required, one of: `not_found, forbidden, unauthenticated, validation_failed, conflict, rate_limited, payment_required, not_implemented, internal`)
- `error.message` (`string`, required)
- `error.details` (`Record<string, unknown>`)

```json
{
  "error": {
    "code": "not_found",
    "message": "<string>",
    "details": {}
  }
}
```

**Example request**

```bash
curl --request GET \
  --url 'https://studio.grid82.app/v1/organizations/<organizationId>/billing/upcoming' \
  --header 'Authorization: Bearer <token>'
```
