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

# Get CFDI Usage

> Authenticate with either a Supabase session (member of `organizationId`) or an API key (external integrations, requires the `read:invoices` scope). Returns how many CFDI the organization has stamped this calendar month (Mexico City time) against its plan's included quota. `cfdiIncluded`/`cfdiRemaining` are `null` for the enterprise plan (unlimited).

Returns how many CFDI the organization has stamped this calendar month (Mexico City time) against its plan's included quota.

> **API key only:** you can also call this without `organizationId` in the URL — `GET /usage` instead of `GET /organizations/{organizationId}/usage` — when authenticating with an API key. The organization is resolved from the key. This form rejects session auth (403).

## Authentication

Accepts **either**:

* A Supabase Bearer session (`Authorization: Bearer <token>`) — the authenticated user must be a member of `organizationId`.
* An API key (`X-API-Key: sk_...`) with the `read:invoices` scope — the key's own organization must match `organizationId` in the URL, or the request is rejected with `403 Forbidden`.

## Path Parameters

| Parameter        | Type          | Required | Description     |
| ---------------- | ------------- | -------- | --------------- |
| `organizationId` | string (UUID) | Yes      | Organization ID |

## Example Request

```bash cURL theme={null}
curl -X GET https://api.timbrix.mx/organizations/550e8400-e29b-41d4-a716-446655440000/usage \
  -H "Authorization: Bearer <your_token>"
```

```typescript TypeScript SDK theme={null}
const usage = await timbrix.invoices.usage(
  "550e8400-e29b-41d4-a716-446655440000"
)
console.log(usage.cfdiUsedThisMonth, usage.cfdiIncluded)
```

## Example Response

```json theme={null}
{
  "plan": "pro",
  "cfdiIncluded": 500,
  "cfdiUsedThisMonth": 128,
  "cfdiRemaining": 372,
  "periodResetsAt": "2026-09-01T06:00:00.000Z"
}
```

| Field               | Type                                                     | Description                                                                      |
| ------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `plan`              | `"starter"` \| `"pro"` \| `"business"` \| `"enterprise"` | The organization's current subscription plan                                     |
| `cfdiIncluded`      | integer \| `null`                                        | CFDI included in the plan this month — `null` on the enterprise plan (unlimited) |
| `cfdiUsedThisMonth` | integer                                                  | CFDI stamped so far this calendar month                                          |
| `cfdiRemaining`     | integer \| `null`                                        | `cfdiIncluded - cfdiUsedThisMonth` — `null` on the enterprise plan (unlimited)   |
| `periodResetsAt`    | string                                                   | ISO 8601 timestamp of the next monthly reset                                     |

## Common Errors

### 401 Unauthorized

Missing or invalid Bearer token / API key.

### 403 Forbidden

The authenticated user is not a member of `organizationId`, or the API key belongs to a different organization than the one in the URL.

### 404 Not Found

`organizationId` not found.


## OpenAPI

````yaml GET /organizations/{organizationId}/usage
openapi: 3.1.0
info:
  title: Timbrix API
  description: >-
    REST API with OAuth2 server for managing organizations, members, and
    webhooks
  version: '1.0'
  contact: {}
servers:
  - url: https://api.timbrix.mx
    description: Production
security: []
tags:
  - name: organizations
    description: Organization management endpoints
  - name: oauth
    description: OAuth2 authentication and authorization
  - name: webhooks
    description: Webhook configuration and delivery
  - name: users
    description: User information endpoints
  - name: api-keys
    description: API Keys management and validation
paths:
  /organizations/{organizationId}/usage:
    get:
      tags:
        - invoices
      summary: Get CFDI usage/quota for the current billing month
      description: >-
        Authenticate with either a Supabase session (member of `organizationId`)
        or an API key (external integrations, requires the `read:invoices`
        scope). Returns how many CFDI the organization has stamped this calendar
        month (Mexico City time) against its plan's included quota.
        `cfdiIncluded`/`cfdiRemaining` are `null` for the enterprise plan
        (unlimited).
      operationId: InvoicesController_usage
      parameters:
        - name: organizationId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponseDto'
        '403':
          description: API key does not belong to `organizationId`
        '404':
          description: organizationId not found
      security:
        - apiKey: []
        - bearer: []
components:
  schemas:
    UsageResponseDto:
      type: object
      properties:
        plan:
          type: string
          enum:
            - starter
            - pro
            - business
            - enterprise
        cfdiIncluded:
          type: object
          example: 500
          nullable: true
          description: null = ilimitado (plan enterprise)
        cfdiUsedThisMonth:
          type: number
          example: 128
        cfdiRemaining:
          type: object
          example: 372
          nullable: true
          description: null = ilimitado (plan enterprise)
        periodResetsAt:
          type: string
          example: '2026-09-01T06:00:00.000Z'
      required:
        - plan
        - cfdiIncluded
        - cfdiUsedThisMonth
        - cfdiRemaining
        - periodResetsAt
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API Key for authentication (format: sk_...)'
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````