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

# Billing

> Retrieve your workspace billing arrangement, pricing, balances, payment method, and history.

Retrieve the billing arrangement, configured pricing, balance or unbilled charges, payment method, and billing history for the workspace associated with your API key.

```text theme={null}
GET /v1/billing
```

This endpoint is read-only. It does not buy credits, change plans or payment methods, update auto-reload settings, or pay invoices.

## Authentication

All requests require a workspace API key:

```http theme={null}
Authorization: Bearer 1eye_live_xxxxxxxxx
```

The examples use `$API_KEY` for your API key. The key determines the workspace; you do not supply a workspace ID. See [Authentication](https://docs.1eye.ai/api-reference/auth.md).

## Request

```bash theme={null}
curl "https://api.1eye.ai/v1/billing" \
  -H "Authorization: Bearer $API_KEY"
```

No query parameters, sorting, or pagination are supported.

## Response

**200 OK** — returns one Billing object directly.

All workspaces use the same top-level structure. `plan` and `payment_collection` identify the billing arrangement:

| Arrangement | `plan` | `payment_collection` |
| - | - | - |
| Standard prepaid | `prepaid` | `card` |
| Contract prepaid | `prepaid` | `invoice` |
| Card postpaid | `postpaid` | `card` |
| Invoice postpaid | `postpaid` | `invoice` |

Exactly one accounting object is populated: prepaid workspaces have `prepaid` and `postpaid: null`; postpaid workspaces have `prepaid: null` and `postpaid`.

### Example: standard prepaid

```json theme={null}
{
  "client_id": "wor_123456789012345678",
  "plan": "prepaid",
  "payment_collection": "card",
  "currency": "USD",
  "price_per_credit": "0.05",
  "credit_costs": {
    "buyer": 2,
    "signal": 1,
    "email": 2,
    "phone": 5
  },
  "prepaid": {
    "credit_balance": 8000,
    "total_credits_added": 9000,
    "total_credits_consumed": 1000,
    "spent_this_month": "200.00",
    "auto_reload": {
      "enabled": true,
      "threshold": 1000,
      "amount": "20.00",
      "credits": 400
    },
    "monthly_limit": {
      "enabled": true,
      "amount": "1000.00"
    }
  },
  "postpaid": null,
  "payment_method": {
    "type": "card",
    "network": "visa",
    "last4": "4242"
  },
  "billing_history": [
    {
      "id": "pay_123456789012345678",
      "type": "reload",
      "status": "paid",
      "amount": "200.00",
      "credits": 4000,
      "invoice_url": "https://example.com/invoices/snowbricks-prepaid.pdf",
      "created_at": "2026-10-20T18:00:00Z"
    },
    {
      "id": "grt_123456789012345678",
      "type": "grant",
      "status": "paid",
      "amount": "0.00",
      "credits": 5000,
      "invoice_url": null,
      "created_at": "2026-10-18T18:00:00Z"
    }
  ]
}
```

All names, domains, identifiers, amounts, URLs, and timestamps in these examples are illustrative.

## Billing fields

| Field | Type | Description |
| - | - | - |
| `client_id` | string | Authenticated Workspace ID. |
| `plan` | string | `prepaid` or `postpaid`. |
| `payment_collection` | string | `card` or `invoice`. |
| `currency` | string | Billing currency, initially `USD`. |
| `price_per_credit` | decimal string | Current configured money price per credit. |
| `credit_costs` | object | Credits per `buyer`, `signal`, `email`, and `phone` activity. |
| `prepaid` | object or null | Balance, lifetime credit totals, and purchase settings. |
| `postpaid` | object or null | Current-month consumption, accrued charges, and payment terms. |
| `payment_method` | object or null | Configured or preferred payment method. |
| `billing_history` | array | Customer-facing billing transactions, invoices, and grants. |

Money values are decimal strings such as `"20.00"`; credit quantities and activity costs are integers. Example prices are illustrative, not universal rates. `credit_costs` matches [Usage](https://docs.1eye.ai/api-reference/usage.md).

## Prepaid accounting

| Field | Type | Description |
| - | - | - |
| `credit_balance` | integer | Credits currently available. |
| `total_credits_added` | integer | Lifetime funded purchases, grants, and positive adjustments. |
| `total_credits_consumed` | integer | Lifetime consumption net of reversed consumption. |
| `spent_this_month` | decimal string | Net confirmed prepaid payments collected this calendar month. |
| `auto_reload` | object or null | Automatic purchase configuration, when applicable. |
| `monthly_limit` | object or null | Monthly cap on automatic reload spending, when applicable. |

`spent_this_month` measures payments, rather than credits consumed multiplied by current pricing. Lifetime credits added can include free grants.

`auto_reload` contains `enabled`, the credit-balance `threshold`, the purchase `amount`, and the purchased `credits`. `monthly_limit` contains `enabled` and its money `amount`. A disabled configuration may retain its saved values; `null` means the feature is not applicable or has no configuration.

### Example: contract prepaid

This is an alternative fictional account arrangement. Invoice collection can use a card or bank transfer; it does not require bank transfer in every case. Contract prepaid does not use auto reload or its monthly limit.

```json theme={null}
{
  "client_id": "wor_123456789012345678",
  "plan": "prepaid",
  "payment_collection": "invoice",
  "currency": "USD",
  "price_per_credit": "0.04",
  "credit_costs": {
    "buyer": 2,
    "signal": 1,
    "email": 2,
    "phone": 5
  },
  "prepaid": {
    "credit_balance": 10000,
    "total_credits_added": 11000,
    "total_credits_consumed": 1000,
    "spent_this_month": "400.00",
    "auto_reload": null,
    "monthly_limit": null
  },
  "postpaid": null,
  "payment_method": {
    "type": "bank_transfer"
  },
  "billing_history": [
    {
      "id": "inv_123456789012345678",
      "type": "prepaid",
      "status": "paid",
      "amount": "400.00",
      "credits": 10000,
      "invoice_url": "https://example.com/invoices/snowbricks-contract-prepaid.pdf",
      "created_at": "2026-10-20T18:00:00Z"
    },
    {
      "id": "grt_123456789012345678",
      "type": "grant",
      "status": "paid",
      "amount": "0.00",
      "credits": 1000,
      "invoice_url": null,
      "created_at": "2026-10-18T18:00:00Z"
    }
  ]
}
```

## Postpaid accounting

| Field | Type | Description |
| - | - | - |
| `credits_consumed_this_month` | integer | Credits consumed in the current calendar month. |
| `unbilled_amount_this_month` | decimal string | Accrued charges not yet invoiced this month. |
| `payment_terms_days` | integer | Nonnegative number of days allowed after invoice issuance. |

Postpaid usage resets with the authoritative billing calendar month. Historical invoices remain in `billing_history`. Usage and Billing follow the same accounting boundaries.

### Example: card postpaid

Payment is due immediately and collected using the configured card; `payment_terms_days` is `0`.

```json theme={null}
{
  "client_id": "wor_123456789012345678",
  "plan": "postpaid",
  "payment_collection": "card",
  "currency": "USD",
  "price_per_credit": "0.05",
  "credit_costs": {
    "buyer": 2,
    "signal": 1,
    "email": 2,
    "phone": 5
  },
  "prepaid": null,
  "postpaid": {
    "credits_consumed_this_month": 145,
    "unbilled_amount_this_month": "7.25",
    "payment_terms_days": 0
  },
  "payment_method": {
    "type": "card",
    "network": "visa",
    "last4": "4242"
  },
  "billing_history": [
    {
      "id": "pay_987654321098765432",
      "type": "postpaid",
      "status": "paid",
      "amount": "50.00",
      "credits": 1000,
      "invoice_url": "https://example.com/invoices/snowbricks-card-postpaid.pdf",
      "created_at": "2026-10-01T07:00:00Z"
    }
  ]
}
```

### Example: invoice postpaid

The customer pays issued invoices under the configured terms. This example uses Net 30; the actual value follows the billing agreement and is not a fixed enum. Invoice collection may use a card or bank transfer.

```json theme={null}
{
  "client_id": "wor_123456789012345678",
  "plan": "postpaid",
  "payment_collection": "invoice",
  "currency": "USD",
  "price_per_credit": "0.04",
  "credit_costs": {
    "buyer": 2,
    "signal": 1,
    "email": 2,
    "phone": 5
  },
  "prepaid": null,
  "postpaid": {
    "credits_consumed_this_month": 145,
    "unbilled_amount_this_month": "5.80",
    "payment_terms_days": 30
  },
  "payment_method": {
    "type": "bank_transfer"
  },
  "billing_history": [
    {
      "id": "inv_987654321098765432",
      "type": "postpaid",
      "status": "unpaid",
      "amount": "100.00",
      "credits": 2500,
      "invoice_url": "https://example.com/invoices/snowbricks-invoice-postpaid.pdf",
      "created_at": "2026-10-01T07:00:00Z"
    }
  ]
}
```

## Payment method

Card display metadata uses `type`, `network`, and `last4`. A bank-transfer method uses `{"type": "bank_transfer"}`. `payment_method: null` means no method is configured.

`payment_collection` describes the collection arrangement; `payment_method` describes the preferred or configured method. They should not be inferred from one another. Full card or bank account information and processor credentials are never returned.

## Billing history

History is ordered newest first by `created_at` and includes the workspace's customer-facing history across prior billing arrangements. The same transaction structure is used for all models.

| Field | Type | Description |
| - | - | - |
| `id` | string | Stable public transaction, grant, or invoice identifier. |
| `type` | string | `grant`, `reload`, `prepaid`, or `postpaid`. |
| `status` | string | `paid`, `unpaid`, or `voided`. |
| `amount` | decimal string | Transaction or invoice amount. |
| `credits` | integer | Credit quantity associated with the record. |
| `invoice_url` | string or null | Authorized invoice document link, when available. |
| `created_at` | datetime | Transaction or invoice issuance timestamp in UTC. |

### Types and statuses

* `grant`: free credits; `amount` is `"0.00"`, status is `paid`, and an invoice link may be absent.
* `reload`: self-service prepaid credit purchase.
* `prepaid`: funded contract prepaid purchase.
* `postpaid`: monthly usage invoice.

`paid` means fully settled or a free grant. `unpaid` includes an issued invoice awaiting payment, including a partially paid invoice or one with a failed payment attempt. `voided` means canceled and no longer payable. These are financial statuses; the API does not expose every internal payment-attempt state.

An unavailable invoice document uses `invoice_url: null`. History is returned in the Billing response rather than through a paginated subresource.

## Related APIs

Use [Usage](https://docs.1eye.ai/api-reference/usage.md) for daily and monthly activity reporting and [Workspace Info](https://docs.1eye.ai/api-reference/workspace.md) for the billing contact. Financial configuration changes follow the existing 1eye billing workflows.

## Errors

| Status | Error code | Description |
| - | - | - |
| 400 | `invalid_parameter` | A request field or query parameter is invalid. |
| 401 | `authentication_error` | The API key is missing, invalid, or revoked. |
| 403 | `permission_denied` | The key does not have permission for this operation. |
| 429 | `rate_limit_exceeded` | The workspace API rate limit was exceeded. |
| 500 | `internal_error` | An unexpected server error occurred. |
| 503 | `service_unavailable` | The service is temporarily unavailable. |

Errors use the standard [error envelope](https://docs.1eye.ai/api-reference/errors.md). Use `request_id` when contacting support.


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