---
# @generated by sylphx-gen 0.1.0 from contracts@190f1b33b937c1aef79697684018db853389b521c75e19ff69ac6af609e96f45. Do not edit.
title: "Usage invoices"
description: "The `usage_invoices` collection of Sylphx Money: A Usage Invoice is Money's own invoice for a subject's usage."
type: reference
product: payments
summary: "A Usage Invoice is Money's own invoice for a subject's usage."
updated: 2026-09-28
order: 900
---

A Usage Invoice is Money's own invoice for a subject's usage. A `threshold` invoice is cut mid-month; the `period` invoice nets those off.

**Service** Sylphx Money · **Resource type** `money.sylphx.com/UsageInvoice` · **Name pattern** `orgs/{org}/projects/{project}/envs/{env}/usage_invoices/{usage_invoice}` · **Shape** `record`

## Fields

| Field | Type | What it is |
| --- | --- | --- |
| `name` | `string` | `orgs/{org}/projects/{project}/envs/{env}/usage_invoices/{usage_invoice}`. |
| `uid` | `string` | `uinv_<cell><ulid>`; never reused. Output only. |
| `meta` | `ResourceMeta` | Resource metadata. |
| `number` | `string` | The invoice number. Output only. |
| `subject` | `Subject` | Who owes it. Output only. |
| `period` | `string` | The month, `YYYY-MM`. Output only. |
| `kind` | `string` | `period` or `threshold`. Output only. |
| `state` | `string` | `tax_pending`, `issued`, or `void`. Output only. |
| `tax_pending_reason` | `string` | Why it is not issued yet, when `tax_pending` (for example `location_required`, `grant_tax_treatment`). Output only. |
| `gross_minor` | `string` | The amounts, minor units, decimal strings. Output only. |
| `subtotal_minor` | `string` | Before tax. Output only. |
| `tax_minor` | `string` | The tax. Output only. |
| `post_tax_credit_minor` | `string` | Credit settled after tax. Output only. |
| `total_minor` | `string` | What is owed: subtotal plus tax minus post-tax credit. Output only. |
| `amount_paid_minor` | `string` | Paid so far. Output only. |
| `collection_mode` | `string` | `standard` or `hold`, fixed at issue. Output only. |
| `issue_time` | `timestamp` | When it was issued. Output only. |
| `due_time` | `timestamp` | When it is due. Output only. |

## Methods

Every method of the collection, in the registry's order, with the scope it
needs. The full request, response and examples are one link away.

| Method | Call | What it does |
| --- | --- | --- |
| `GET` | [`get`](/docs/api/usage_invoices#get) | Gets a usage invoice. |
| `GET` | [`list`](/docs/api/usage_invoices#list) | Lists usage invoices, newest first. |
| `POST` | [`release_collection`](/docs/api/usage_invoices#release-collection) | Releases a held invoice for collection, audited with who and why. Grant expiry or replacement never does. |

## get

Gets a usage invoice.

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/usage_invoices/usage-invoice` · scope `billing:read` · effect `read` · [Request, response and examples](/docs/api/usage_invoices/get)

## list

Lists usage invoices, newest first.

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/usage_invoices` · scope `billing:read` · effect `read` · paginated · [Request, response and examples](/docs/api/usage_invoices/list)

## release_collection

Releases a held invoice for collection, audited with who and why. Grant expiry or replacement never does.

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/usage_invoices/usage-invoice:releaseCollection` · scope `billing:credits.approve` · effect `write` · [Request, response and examples](/docs/api/usage_invoices/release_collection)