> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-graphql-api/products/billing/api-reference/invoice.md).

# Invoices

The invoices of the caller's workspace: what each one charges for each billing period, its lines, its status, and the queries that read them.

## Queries

### myInvoice

One of the caller's own workspace's invoices; null when it does not exist or belongs to another workspace.

```graphql
myInvoice(id: ID!): BillingWorkspaceInvoice
```

**Arguments**

| Name | Type  | Description                        |
| ---- | ----- | ---------------------------------- |
| `id` | `ID!` | The ID of the invoice to retrieve. |

**Output types:**

<details>

<summary>BillingWorkspaceInvoice</summary>

One of the caller's own workspace's invoices: its charge for every complete billing period of its subscriptions that no invoice covered yet, as of one pass. `periodStart` and `periodEnd` span the periods covered. The total is posted to the balance as the `INVOICE` entry on its statement.

`status` is `PAID` at issue when the balance covers the total, and `ISSUED` when the invoice opens a debt. Payments are not tied to invoices and settle the oldest invoices first; the payment that covers an invoice marks it `PAID` and sets `paidAt`. Once the grace period has passed (`dueAt`), the daily pass marks an unpaid one `OVERDUE`.

| Field           | Type                                                                        | Description                                                                                                                      |
| --------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `id`            | `ID!`                                                                       |                                                                                                                                  |
| `workspaceId`   | `ID!`                                                                       | The workspace being charged: the one the token names.                                                                            |
| `invoiceNumber` | `String!`                                                                   | The number shown to people, unique across all invoices of the platform.                                                          |
| `periodStart`   | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime)! | First instant of the earliest billing period covered.                                                                            |
| `periodEnd`     | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime)! | End of the latest billing period covered, exclusive.                                                                             |
| `subtotal`      | [Money](/docs/navixy-graphql-api/core-api-reference/common.md#money)!       | Sum of the line items, before adjustments.                                                                                       |
| `priceModify`   | [Money](/docs/navixy-graphql-api/core-api-reference/common.md#money)!       | Signed adjustment applied to the subtotal — a discount is negative.                                                              |
| `total`         | [Money](/docs/navixy-graphql-api/core-api-reference/common.md#money)!       | What the customer owes: `subtotal` plus `priceModify`.                                                                           |
| `status`        | [BillingInvoiceStatus](#billinginvoicestatus)!                              | Current lifecycle status.                                                                                                        |
| `issuedAt`      | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime)! | When the invoice was issued. Its place in a list is this, not `createdAt`.                                                       |
| `dueAt`         | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime)! | When payment is due.                                                                                                             |
| `paidAt`        | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime)  | When it was paid; null while it is not.                                                                                          |
| `lineItems`     | \[[BillingWorkspaceInvoiceLineItem](#billingworkspaceinvoicelineitem)!]!    | The lines, in display order: per covered period, the period fees, then every metric of the plan, then the line-item submissions. |
| `createdAt`     | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime)! |                                                                                                                                  |
| `updatedAt`     | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime)! |                                                                                                                                  |

</details>

***

### myInvoices

The caller's own workspace's invoices, newest issue date first.

**The workspace is not an argument.** It is the one the caller's token names; a token carrying no workspace claim is refused.

```graphql
myInvoices(
    filter: BillingWorkspaceInvoiceFilter
    first: Int
    after: String
    last: Int
    before: String
    orderBy: BillingInvoiceOrder = { field: ISSUED_AT, direction: DESC }
  ): BillingWorkspaceInvoiceConnection!
```

**Arguments**

| Name      | Type                            | Description                                                                                   |
| --------- | ------------------------------- | --------------------------------------------------------------------------------------------- |
| `filter`  | `BillingWorkspaceInvoiceFilter` | Filtering options for the returned invoices.                                                  |
| `first`   | `Int`                           | The first `n` elements from the [paginated list](/docs/navixy-graphql-api/pagination.md).     |
| `after`   | `String`                        | The elements that come after the specified [cursor](/docs/navixy-graphql-api/pagination.md).  |
| `last`    | `Int`                           | The last `n` elements from the [paginated list](/docs/navixy-graphql-api/pagination.md).      |
| `before`  | `String`                        | The elements that come before the specified [cursor](/docs/navixy-graphql-api/pagination.md). |
| `orderBy` | `BillingInvoiceOrder`           | The ordering options for the returned invoices.                                               |

**Input types:**

<details>

<summary>BillingWorkspaceInvoiceFilter</summary>

Filtering options for the caller's own invoices. Fields combine with AND.

| Field        | Type                                                                       | Description                                          |
| ------------ | -------------------------------------------------------------------------- | ---------------------------------------------------- |
| `status`     | [BillingInvoiceStatus](#billinginvoicestatus)                              | Keep only invoices in this status.                   |
| `issuedFrom` | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime) | Keep only invoices issued at or after this instant.  |
| `issuedTo`   | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime) | Keep only invoices issued at or before this instant. |

</details>

<details>

<summary>BillingInvoiceOrder</summary>

Ordering options for invoices.

| Field       | Type                                                                                    | Description             |
| ----------- | --------------------------------------------------------------------------------------- | ----------------------- |
| `field`     | [BillingInvoiceOrderField](#billinginvoiceorderfield)!                                  | The field to order by.  |
| `direction` | [OrderDirection](/docs/navixy-graphql-api/core-api-reference/common.md#orderdirection)! | The direction to order. |

</details>

**Output types:**

<details>

<summary>BillingWorkspaceInvoiceConnection</summary>

A page of the caller's own workspace's invoices.

**Implements:** [Connection](/docs/navixy-graphql-api/core-api-reference/common.md#connection)

| Field      | Type                                                                         | Description                                                |
| ---------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `edges`    | \[[BillingWorkspaceInvoiceEdge](#billingworkspaceinvoiceedge)!]!             | A list of edges.                                           |
| `nodes`    | \[[BillingWorkspaceInvoice](#billingworkspaceinvoice)!]!                     | A list of nodes in the connection (without edge metadata). |
| `pageInfo` | [PageInfo](/docs/navixy-graphql-api/core-api-reference/common.md#pageinfo)!  | Information about the current page.                        |
| `total`    | [CountInfo](/docs/navixy-graphql-api/core-api-reference/common.md#countinfo) | The total count of items matching the filter.              |

</details>

***

## Objects

### BillingWorkspaceInvoice

One of the caller's own workspace's invoices: its charge for every complete billing period of its subscriptions that no invoice covered yet, as of one pass. `periodStart` and `periodEnd` span the periods covered. The total is posted to the balance as the `INVOICE` entry on its statement.

`status` is `PAID` at issue when the balance covers the total, and `ISSUED` when the invoice opens a debt. Payments are not tied to invoices and settle the oldest invoices first; the payment that covers an invoice marks it `PAID` and sets `paidAt`. Once the grace period has passed (`dueAt`), the daily pass marks an unpaid one `OVERDUE`.

| Field           | Type                                                                        | Description                                                                                                                      |
| --------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `id`            | `ID!`                                                                       |                                                                                                                                  |
| `workspaceId`   | `ID!`                                                                       | The workspace being charged: the one the token names.                                                                            |
| `invoiceNumber` | `String!`                                                                   | The number shown to people, unique across all invoices of the platform.                                                          |
| `periodStart`   | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime)! | First instant of the earliest billing period covered.                                                                            |
| `periodEnd`     | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime)! | End of the latest billing period covered, exclusive.                                                                             |
| `subtotal`      | [Money](/docs/navixy-graphql-api/core-api-reference/common.md#money)!       | Sum of the line items, before adjustments.                                                                                       |
| `priceModify`   | [Money](/docs/navixy-graphql-api/core-api-reference/common.md#money)!       | Signed adjustment applied to the subtotal — a discount is negative.                                                              |
| `total`         | [Money](/docs/navixy-graphql-api/core-api-reference/common.md#money)!       | What the customer owes: `subtotal` plus `priceModify`.                                                                           |
| `status`        | [BillingInvoiceStatus](#billinginvoicestatus)!                              | Current lifecycle status.                                                                                                        |
| `issuedAt`      | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime)! | When the invoice was issued. Its place in a list is this, not `createdAt`.                                                       |
| `dueAt`         | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime)! | When payment is due.                                                                                                             |
| `paidAt`        | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime)  | When it was paid; null while it is not.                                                                                          |
| `lineItems`     | \[[BillingWorkspaceInvoiceLineItem](#billingworkspaceinvoicelineitem)!]!    | The lines, in display order: per covered period, the period fees, then every metric of the plan, then the line-item submissions. |
| `createdAt`     | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime)! |                                                                                                                                  |
| `updatedAt`     | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime)! |                                                                                                                                  |

***

### BillingWorkspaceInvoiceLineItem

One line of a workspace's invoice: a period fee, a metric's priced usage, or a line-item submission passed through. `amount` is `quantity × unitPrice` rounded half up to the minor unit, except on a line-item submission that carried its own amount.

| Field            | Type                                                                                                         | Description                                                                                                                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`             | `ID!`                                                                                                        |                                                                                                                                                                                                         |
| `description`    | `String!`                                                                                                    | What the line charges for, ending with the billing period it belongs to, as `, 2026-01-15 – 2026-02-14`.                                                                                                |
| `quantity`       | `Float!`                                                                                                     | Units charged: the share of the month on a period-fee line, the aggregated usage over the included limit on a metric line, the quantity as submitted on a line-item line. `metric.unit` names the unit. |
| `unitPrice`      | [Money](/docs/navixy-graphql-api/core-api-reference/common.md#money)!                                        | Price of one unit in the invoice's currency.                                                                                                                                                            |
| `amount`         | [Money](/docs/navixy-graphql-api/core-api-reference/common.md#money)!                                        | The line's total.                                                                                                                                                                                       |
| `productDomain`  | [BillingProductDomain](/docs/navixy-graphql-api/products/billing/api-reference/plan.md#billingproductdomain) | The product the line belongs to.                                                                                                                                                                        |
| `metric`         | [BillingMetric](/docs/navixy-graphql-api/products/billing/api-reference/plan.md#billingmetric)               | The metric the line prices; null on a period-fee line and on a line-item submission's line.                                                                                                             |
| `subscriptionId` | `ID`                                                                                                         | The subscription the line charges for, as in `mySubscriptions`.                                                                                                                                         |
| `planId`         | `ID`                                                                                                         | The plan that priced the line; the subscription's branch, when it has one, overrode this plan's fee and prices.                                                                                         |
| `periodStart`    | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime)                                   | First instant of the billing period the line belongs to.                                                                                                                                                |
| `periodEnd`      | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime)                                   | End of that billing period, exclusive.                                                                                                                                                                  |
| `createdAt`      | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime)!                                  |                                                                                                                                                                                                         |

***

## Inputs

### BillingInvoiceOrder

Ordering options for invoices.

| Field       | Type                                                                                    | Description             |
| ----------- | --------------------------------------------------------------------------------------- | ----------------------- |
| `field`     | [BillingInvoiceOrderField](#billinginvoiceorderfield)!                                  | The field to order by.  |
| `direction` | [OrderDirection](/docs/navixy-graphql-api/core-api-reference/common.md#orderdirection)! | The direction to order. |

***

### BillingWorkspaceInvoiceFilter

Filtering options for the caller's own invoices. Fields combine with AND.

| Field        | Type                                                                       | Description                                          |
| ------------ | -------------------------------------------------------------------------- | ---------------------------------------------------- |
| `status`     | [BillingInvoiceStatus](#billinginvoicestatus)                              | Keep only invoices in this status.                   |
| `issuedFrom` | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime) | Keep only invoices issued at or after this instant.  |
| `issuedTo`   | [DateTime](/docs/navixy-graphql-api/core-api-reference/common.md#datetime) | Keep only invoices issued at or before this instant. |

***

## Enums

### BillingInvoiceStatus

Lifecycle of an invoice. Billing writes ISSUED, PAID and OVERDUE; DRAFT and VOID are reserved and never set.

| Value     | Description                                   |
| --------- | --------------------------------------------- |
| `DRAFT`   | Assembled but not yet issued to the customer. |
| `ISSUED`  | Issued and outstanding.                       |
| `PAID`    | Settled.                                      |
| `OVERDUE` | Issued, past its due date, still outstanding. |
| `VOID`    | Cancelled without being paid.                 |

***

### BillingInvoiceOrderField

Fields available for ordering invoices.

| Value       | Description                              |
| ----------- | ---------------------------------------- |
| `ISSUED_AT` | Order by the day the invoice was issued. |

***

## Pagination types

### BillingWorkspaceInvoiceConnection

A page of the caller's own workspace's invoices.

**Implements:** [Connection](/docs/navixy-graphql-api/core-api-reference/common.md#connection)

| Field      | Type                                                                         | Description                                                |
| ---------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `edges`    | \[[BillingWorkspaceInvoiceEdge](#billingworkspaceinvoiceedge)!]!             | A list of edges.                                           |
| `nodes`    | \[[BillingWorkspaceInvoice](#billingworkspaceinvoice)!]!                     | A list of nodes in the connection (without edge metadata). |
| `pageInfo` | [PageInfo](/docs/navixy-graphql-api/core-api-reference/common.md#pageinfo)!  | Information about the current page.                        |
| `total`    | [CountInfo](/docs/navixy-graphql-api/core-api-reference/common.md#countinfo) | The total count of items matching the filter.              |

***

### BillingWorkspaceInvoiceEdge

An edge in the BillingWorkspaceInvoice connection.

**Implements:** [Edge](/docs/navixy-graphql-api/core-api-reference/common.md#edge)

| Field    | Type                                                 | Description                         |
| -------- | ---------------------------------------------------- | ----------------------------------- |
| `cursor` | `String!`                                            | An opaque cursor for this edge.     |
| `node`   | [BillingWorkspaceInvoice](#billingworkspaceinvoice)! | The invoice at the end of the edge. |

***

## See also

* [Pagination](/docs/navixy-graphql-api/pagination.md)
* [Filtering and sorting](/docs/navixy-graphql-api/filtering-and-sorting.md)
* [Error handling](/docs/navixy-graphql-api/error-handling.md)
* [Optimistic locking](/docs/navixy-graphql-api/optimistic-locking.md)
* [Limits](/docs/navixy-graphql-api/limits.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://navixy.com/docs/navixy-graphql-api/products/billing/api-reference/invoice.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.