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

# Monthly invoices

> The monthly invoices of your organisation, with everything charged apart from the plan, and the upgrade suggestion.

```text theme={null}
GET /v1/tenant/monthly-invoices
```

Returns the monthly invoices of your organisation, newest first (up to 36). Each one has everything charged apart from your plan in that month, one line per charge: communications through wede above what the plan includes, units above the plan for each day they were above, production events above the yearly limit, and the fee per production event when your plan has one. It also returns the fee per event of your current plan and, when it applies, the plan Billing suggests. See [The monthly invoice](https://docs.wede.pt/concepts/plans.md#the-monthly-invoice).

The licence of your plan is invoiced on its own, once a year, and never appears here.

## Authentication

API key or session token with the `billing:view` permission. API keys have it.

## Example

```bash theme={null}
curl https://api.wede.pt/v1/tenant/monthly-invoices \
  -H "x-wede-api-key: wede_live_YOUR_KEY"
```

## Response

`200 OK`. Values below are illustrative.

```json theme={null}
{
  "event_fee": null,
  "currency": "EUR",
  "upgrade": null,
  "data": [
    {
      "period": "2026-11",
      "status": "issued",
      "lines": [
        { "kind": "communications", "channel": "sms", "units": 1000, "unit_price": 0.05, "amount": 50 },
        { "kind": "stock", "item": "user", "unit_days": 12, "price_per_day": 0.5, "amount": 6 },
        { "kind": "events", "events": 40, "limit": 1000000, "unit_price": 0.01, "amount": 0.4 }
      ],
      "amount": 56.4,
      "comm_amount": 50,
      "stock_amount": 6.4,
      "fee_amount": 0,
      "fee_events": 0,
      "currency": "EUR",
      "invoice_url": "https://invoice.example/..."
    }
  ]
}
```

**event\_fee** `number | null`

The fee per production event of your current plan, or `null` when it has none.

**currency** `string`

The currency of your country, ISO 4217.

**upgrade** `object | null`

The plan Billing suggests, or `null`. It is suggested when what was charged above your plan in the last monthly invoice (communications, units and events, without the fee per event) is more than the monthly difference to the next plan by price for your organisation (the difference of the yearly prices divided by 12). A month with nothing above the plan clears it.

**properties**

**plan\_id** `string`

The suggested plan. Its conditions are in [Plans of your organisation](https://docs.wede.pt/api-reference/tenant/plans.md).

**plan\_name** `string`

Its name.

**period** `string`

The month of the invoice the suggestion comes from, `YYYY-MM`.

**above\_plan** `number`

What was charged above your plan that month, without the fee per event.

**current\_price\_yearly** `number`

Your current yearly price.

**next\_price\_yearly** `number`

The yearly price of the suggested plan for your organisation.

**monthly\_difference** `number`

The difference of the two yearly prices divided by 12.

**currency** `string`

Currency of these amounts.

**data** `object[]`

The monthly invoices.

**properties**

**period** `string`

The month, `YYYY-MM`.

**status** `string`

`issued`, or `carried` when the month was below 0.50 in your currency and goes on the next invoice.

**lines** `object[]`

One line per charge, by `kind`:

| `kind` | Fields |
| - | - |
| `communications` | `channel`, `units` above what the plan includes, `unit_price`, `amount` |
| `stock` | `item` (`user`, `device`, `zone`, `webhook`, `data_source`), `unit_days` (each unit above, for each day), `price_per_day`, `amount` |
| `events` | `events` above the yearly `limit`, `unit_price`, `amount` |
| `event_fee` | `events` of the month, `fee`, `amount` |

**amount** `number`

Total without tax. Taxes are added on the invoice itself.

**comm\_amount** `number`

The communications part.

**stock\_amount** `number`

The part of units above the plan and of events above the yearly limit, including amounts carried from earlier months.

**fee\_amount** `number`

The fee per event part, including amounts carried from earlier months.

**fee\_events** `integer`

Production events charged with the fee.

**currency** `string`

Currency of the invoice.

**invoice\_url** `string | null`

Link to the invoice, to see and pay it. `null` for a carried month.

## Errors

| Status | Code | When |
| - | - | - |
| 401 | `unauthorized` | Credential missing, malformed, revoked or expired |
| 403 | `forbidden` | The credential lacks `billing:view` |
| 404 | `not_found` | The credential is not linked to a tenant |
| 503 | `service_unavailable` | Not available right now. Retry |


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