# Billing

## Get credit balance

`ai_gateway.billing.credit_balance(BillingCreditBalanceParams**kwargs)  -> BillingCreditBalanceResponse`

**get** `/accounts/{account_id}/ai-gateway/billing/credit-balance`

Retrieve the current credit balance, payment method info, and top-up configuration.

### Parameters

- `account_id: str`

### Returns

- `class BillingCreditBalanceResponse: …`

  - `balance: float`

  - `has_default_payment_method: bool`

  - `payment_method: Optional[PaymentMethod]`

    - `brand: Optional[str]`

    - `last4: Optional[str]`

  - `topup_config: TopupConfig`

    - `amount: Optional[float]`

    - `disabled_reason: Optional[str]`

    - `error: Optional[str]`

    - `last_failed_at: Optional[float]`

    - `threshold: Optional[float]`

  - `first_topup_success: Optional[bool]`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.ai_gateway.billing.credit_balance(
    account_id="account_id",
)
print(response.balance)
```

#### Response

```json
{
  "errors": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "messages": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "result": {
    "balance": 0,
    "has_default_payment_method": true,
    "payment_method": {
      "brand": "brand",
      "last4": "last4"
    },
    "topup_config": {
      "amount": 0,
      "disabledReason": "disabledReason",
      "error": "error",
      "lastFailedAt": 0,
      "threshold": 0
    },
    "first_topup_success": true
  },
  "success": true,
  "result_info": {
    "has_more": true,
    "page": 0,
    "per_page": 0,
    "total_count": 0
  }
}
```

## Get usage history

`ai_gateway.billing.usage_history(BillingUsageHistoryParams**kwargs)  -> BillingUsageHistoryResponse`

**get** `/accounts/{account_id}/ai-gateway/billing/usage-history`

Retrieve aggregated usage meter event summaries for the given time range.

### Parameters

- `account_id: str`

- `value_grouping_window: Literal["day", "hour"]`

  Grouping window for usage data.

  - `"day"`

  - `"hour"`

- `end_time: Optional[float]`

  End time as Unix timestamp in milliseconds.

- `start_time: Optional[float]`

  Start time as Unix timestamp in milliseconds.

### Returns

- `class BillingUsageHistoryResponse: …`

  - `history: List[History]`

    - `id: str`

    - `aggregated_value: float`

    - `end_time: float`

    - `start_time: float`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.ai_gateway.billing.usage_history(
    account_id="account_id",
    value_grouping_window="day",
)
print(response.history)
```

#### Response

```json
{
  "errors": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "messages": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "result": {
    "history": [
      {
        "id": "id",
        "aggregated_value": 0,
        "end_time": 0,
        "start_time": 0
      }
    ]
  },
  "success": true,
  "result_info": {
    "has_more": true,
    "page": 0,
    "per_page": 0,
    "total_count": 0
  }
}
```

## Get invoice history

`ai_gateway.billing.invoice_history(BillingInvoiceHistoryParams**kwargs)  -> BillingInvoiceHistoryResponse`

**get** `/accounts/{account_id}/ai-gateway/billing/invoice-history`

Retrieve a list of past invoices with pagination, optionally filtered by type.

### Parameters

- `account_id: str`

- `type: Optional[Literal["auto", "all", "manual"]]`

  Filter invoice type: auto, manual, or all.

  - `"auto"`

  - `"all"`

  - `"manual"`

### Returns

- `class BillingInvoiceHistoryResponse: …`

  - `invoices: List[Invoice]`

    - `amount_due: float`

    - `amount_paid: float`

    - `amount_remaining: float`

    - `currency: str`

    - `id: Optional[str]`

    - `attempt_count: Optional[float]`

    - `attempted: Optional[bool]`

    - `auto_advance: Optional[bool]`

    - `created: Optional[float]`

    - `created_by: Optional[str]`

    - `description: Optional[str]`

    - `invoice_origin: Optional[str]`

    - `invoice_pdf: Optional[str]`

    - `status: Optional[str]`

  - `pagination: Pagination`

    - `has_more: bool`

    - `page: float`

    - `per_page: float`

    - `total_count: float`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.ai_gateway.billing.invoice_history(
    account_id="account_id",
)
print(response.invoices)
```

#### Response

```json
{
  "errors": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "messages": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "result": {
    "invoices": [
      {
        "amount_due": 0,
        "amount_paid": 0,
        "amount_remaining": 0,
        "currency": "currency",
        "id": "id",
        "attempt_count": 0,
        "attempted": true,
        "auto_advance": true,
        "created": 0,
        "created_by": "created_by",
        "description": "description",
        "invoice_origin": "invoice_origin",
        "invoice_pdf": "invoice_pdf",
        "status": "status"
      }
    ],
    "pagination": {
      "has_more": true,
      "page": 0,
      "per_page": 0,
      "total_count": 0
    }
  },
  "success": true,
  "result_info": {
    "has_more": true,
    "page": 0,
    "per_page": 0,
    "total_count": 0
  }
}
```

## Get invoice preview

`ai_gateway.billing.invoice_preview(BillingInvoicePreviewParams**kwargs)  -> BillingInvoicePreviewResponse`

**get** `/accounts/{account_id}/ai-gateway/billing/invoice-preview`

Retrieve a preview of the upcoming invoice including line items and tax.

### Parameters

- `account_id: str`

### Returns

- `class BillingInvoicePreviewResponse: …`

  - `id: str`

  - `amount_due: float`

  - `amount_paid: float`

  - `amount_remaining: float`

  - `currency: str`

  - `invoice_lines: List[InvoiceLine]`

    - `amount: float`

    - `currency: str`

    - `description: Optional[str]`

    - `period: InvoiceLinePeriod`

      - `end: float`

      - `start: float`

    - `pricing: InvoiceLinePricing`

      - `unit_amount_decimal: Optional[str]`

    - `quantity: float`

    - `pretax_credit_amounts: Optional[List[InvoiceLinePretaxCreditAmount]]`

      - `amount: float`

      - `type: str`

      - `credit_balance_transaction: Optional[str]`

      - `discount: Optional[str]`

  - `period_end: float`

  - `period_start: float`

  - `status: Literal["draft", "open", "paid", 2 more]`

    - `"draft"`

    - `"open"`

    - `"paid"`

    - `"uncollectible"`

    - `"void"`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.ai_gateway.billing.invoice_preview(
    account_id="account_id",
)
print(response.id)
```

#### Response

```json
{
  "errors": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "messages": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "result": {
    "id": "id",
    "amount_due": 0,
    "amount_paid": 0,
    "amount_remaining": 0,
    "currency": "currency",
    "invoice_lines": [
      {
        "amount": 0,
        "currency": "currency",
        "description": "description",
        "period": {
          "end": 0,
          "start": 0
        },
        "pricing": {
          "unit_amount_decimal": "unit_amount_decimal"
        },
        "quantity": 0,
        "pretax_credit_amounts": [
          {
            "amount": 0,
            "type": "type",
            "credit_balance_transaction": "credit_balance_transaction",
            "discount": "discount"
          }
        ]
      }
    ],
    "period_end": 0,
    "period_start": 0,
    "status": "draft"
  },
  "success": true,
  "result_info": {
    "has_more": true,
    "page": 0,
    "per_page": 0,
    "total_count": 0
  }
}
```

## Domain Types

### Billing Credit Balance Response

- `class BillingCreditBalanceResponse: …`

  - `balance: float`

  - `has_default_payment_method: bool`

  - `payment_method: Optional[PaymentMethod]`

    - `brand: Optional[str]`

    - `last4: Optional[str]`

  - `topup_config: TopupConfig`

    - `amount: Optional[float]`

    - `disabled_reason: Optional[str]`

    - `error: Optional[str]`

    - `last_failed_at: Optional[float]`

    - `threshold: Optional[float]`

  - `first_topup_success: Optional[bool]`

### Billing Usage History Response

- `class BillingUsageHistoryResponse: …`

  - `history: List[History]`

    - `id: str`

    - `aggregated_value: float`

    - `end_time: float`

    - `start_time: float`

### Billing Invoice History Response

- `class BillingInvoiceHistoryResponse: …`

  - `invoices: List[Invoice]`

    - `amount_due: float`

    - `amount_paid: float`

    - `amount_remaining: float`

    - `currency: str`

    - `id: Optional[str]`

    - `attempt_count: Optional[float]`

    - `attempted: Optional[bool]`

    - `auto_advance: Optional[bool]`

    - `created: Optional[float]`

    - `created_by: Optional[str]`

    - `description: Optional[str]`

    - `invoice_origin: Optional[str]`

    - `invoice_pdf: Optional[str]`

    - `status: Optional[str]`

  - `pagination: Pagination`

    - `has_more: bool`

    - `page: float`

    - `per_page: float`

    - `total_count: float`

### Billing Invoice Preview Response

- `class BillingInvoicePreviewResponse: …`

  - `id: str`

  - `amount_due: float`

  - `amount_paid: float`

  - `amount_remaining: float`

  - `currency: str`

  - `invoice_lines: List[InvoiceLine]`

    - `amount: float`

    - `currency: str`

    - `description: Optional[str]`

    - `period: InvoiceLinePeriod`

      - `end: float`

      - `start: float`

    - `pricing: InvoiceLinePricing`

      - `unit_amount_decimal: Optional[str]`

    - `quantity: float`

    - `pretax_credit_amounts: Optional[List[InvoiceLinePretaxCreditAmount]]`

      - `amount: float`

      - `type: str`

      - `credit_balance_transaction: Optional[str]`

      - `discount: Optional[str]`

  - `period_end: float`

  - `period_start: float`

  - `status: Literal["draft", "open", "paid", 2 more]`

    - `"draft"`

    - `"open"`

    - `"paid"`

    - `"uncollectible"`

    - `"void"`

# Topup

## Create a top-up

`ai_gateway.billing.topup.create(TopupCreateParams**kwargs)  -> TopupCreateResponse`

**post** `/accounts/{account_id}/ai-gateway/billing/topup`

Create a credit top-up via Stripe PaymentIntent for the given account.

### Parameters

- `account_id: str`

- `amount: int`

  Top-up amount in cents (min 1000).

### Returns

- `class TopupCreateResponse: …`

  - `client_secret: Optional[str]`

    Stripe PaymentIntent client secret.

  - `onboarding: bool`

    Whether the user was already onboarded.

  - `payment_intent_id: str`

    Stripe invoice ID.

  - `brand: Optional[str]`

    Card brand (visa, mastercard, etc.).

  - `last4: Optional[str]`

    Last 4 digits of card.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
topup = client.ai_gateway.billing.topup.create(
    account_id="account_id",
    amount=5000,
)
print(topup.payment_intent_id)
```

#### Response

```json
{
  "errors": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "messages": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "result": {
    "client_secret": "client_secret",
    "onboarding": true,
    "payment_intent_id": "payment_intent_id",
    "brand": "brand",
    "last4": "last4"
  },
  "success": true,
  "result_info": {
    "has_more": true,
    "page": 0,
    "per_page": 0,
    "total_count": 0
  }
}
```

## Check top-up status

`ai_gateway.billing.topup.status(TopupStatusParams**kwargs)  -> TopupStatusResponse`

**post** `/accounts/{account_id}/ai-gateway/billing/topup/status`

Get the payment processing status of a top-up by its invoice ID.

### Parameters

- `account_id: str`

- `payment_intent_id: str`

  Stripe invoice ID to check status for.

### Returns

- `class TopupStatusResponse: …`

  - `payment_intent_id: str`

  - `status: Literal["completed", "pending"]`

    - `"completed"`

    - `"pending"`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.ai_gateway.billing.topup.status(
    account_id="account_id",
    payment_intent_id="in_1abc",
)
print(response.payment_intent_id)
```

#### Response

```json
{
  "errors": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "messages": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "result": {
    "payment_intent_id": "payment_intent_id",
    "status": "completed"
  },
  "success": true,
  "result_info": {
    "has_more": true,
    "page": 0,
    "per_page": 0,
    "total_count": 0
  }
}
```

## Domain Types

### Topup Create Response

- `class TopupCreateResponse: …`

  - `client_secret: Optional[str]`

    Stripe PaymentIntent client secret.

  - `onboarding: bool`

    Whether the user was already onboarded.

  - `payment_intent_id: str`

    Stripe invoice ID.

  - `brand: Optional[str]`

    Card brand (visa, mastercard, etc.).

  - `last4: Optional[str]`

    Last 4 digits of card.

### Topup Status Response

- `class TopupStatusResponse: …`

  - `payment_intent_id: str`

  - `status: Literal["completed", "pending"]`

    - `"completed"`

    - `"pending"`

# Config

## Get auto top-up configuration

`ai_gateway.billing.topup.config.get(ConfigGetParams**kwargs)  -> ConfigGetResponse`

**get** `/accounts/{account_id}/ai-gateway/billing/topup/config`

Retrieve the current auto top-up threshold, amount, and any error state.

### Parameters

- `account_id: str`

### Returns

- `class ConfigGetResponse: …`

  - `amount: Optional[float]`

  - `disabled_reason: Optional[str]`

  - `error: Optional[str]`

  - `last_failed_at: Optional[float]`

  - `threshold: Optional[float]`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
config = client.ai_gateway.billing.topup.config.get(
    account_id="account_id",
)
print(config.amount)
```

#### Response

```json
{
  "errors": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "messages": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "result": {
    "amount": 0,
    "disabledReason": "disabledReason",
    "error": "error",
    "lastFailedAt": 0,
    "threshold": 0
  },
  "success": true,
  "result_info": {
    "has_more": true,
    "page": 0,
    "per_page": 0,
    "total_count": 0
  }
}
```

## Set auto top-up configuration

`ai_gateway.billing.topup.config.create(ConfigCreateParams**kwargs)  -> ConfigCreateResponse`

**post** `/accounts/{account_id}/ai-gateway/billing/topup/config`

Configure auto top-up with a balance threshold and top-up amount.

### Parameters

- `account_id: str`

- `amount: int`

  Auto top-up amount in cents (min 1000).

- `threshold: int`

  Balance threshold in cents that triggers auto top-up (min 500).

### Returns

- `class ConfigCreateResponse: …`

  - `amount: float`

  - `threshold: float`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
config = client.ai_gateway.billing.topup.config.create(
    account_id="account_id",
    amount=5000,
    threshold=500,
)
print(config.amount)
```

#### Response

```json
{
  "errors": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "messages": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "result": {
    "amount": 0,
    "threshold": 0
  },
  "success": true,
  "result_info": {
    "has_more": true,
    "page": 0,
    "per_page": 0,
    "total_count": 0
  }
}
```

## Delete auto top-up configuration

`ai_gateway.billing.topup.config.delete(ConfigDeleteParams**kwargs)  -> object`

**delete** `/accounts/{account_id}/ai-gateway/billing/topup/config`

Remove the auto top-up configuration for the account.

### Parameters

- `account_id: str`

### Returns

- `object`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
config = client.ai_gateway.billing.topup.config.delete(
    account_id="account_id",
)
print(config)
```

#### Response

```json
{
  "errors": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "messages": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "result": {},
  "success": true,
  "result_info": {
    "has_more": true,
    "page": 0,
    "per_page": 0,
    "total_count": 0
  }
}
```

## Domain Types

### Config Get Response

- `class ConfigGetResponse: …`

  - `amount: Optional[float]`

  - `disabled_reason: Optional[str]`

  - `error: Optional[str]`

  - `last_failed_at: Optional[float]`

  - `threshold: Optional[float]`

### Config Create Response

- `class ConfigCreateResponse: …`

  - `amount: float`

  - `threshold: float`

# Spending Limit

## Get spending limit

`ai_gateway.billing.spending_limit.get(SpendingLimitGetParams**kwargs)  -> SpendingLimitGetResponse`

**get** `/accounts/{account_id}/ai-gateway/billing/spending-limit`

Retrieve the current spending limit configuration for the account.

### Parameters

- `account_id: str`

### Returns

- `class SpendingLimitGetResponse: …`

  - `config: Config`

    - `amount: Optional[float]`

    - `duration: Optional[str]`

    - `strategy: Optional[str]`

  - `enabled: bool`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
spending_limit = client.ai_gateway.billing.spending_limit.get(
    account_id="account_id",
)
print(spending_limit.config)
```

#### Response

```json
{
  "errors": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "messages": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "result": {
    "config": {
      "amount": 0,
      "duration": "duration",
      "strategy": "strategy"
    },
    "enabled": true
  },
  "success": true,
  "result_info": {
    "has_more": true,
    "page": 0,
    "per_page": 0,
    "total_count": 0
  }
}
```

## Set spending limit

`ai_gateway.billing.spending_limit.create(SpendingLimitCreateParams**kwargs)  -> object`

**post** `/accounts/{account_id}/ai-gateway/billing/spending-limit`

Configure a spending limit with amount, strategy, and duration.

### Parameters

- `account_id: str`

- `amount: int`

  Spending limit amount in cents (min 100).

- `duration: Literal["daily", "weekly", "monthly"]`

  Spending limit duration.

  - `"daily"`

  - `"weekly"`

  - `"monthly"`

- `strategy: Literal["fixed", "sliding"]`

  Spending limit strategy.

  - `"fixed"`

  - `"sliding"`

### Returns

- `object`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
spending_limit = client.ai_gateway.billing.spending_limit.create(
    account_id="account_id",
    amount=10000,
    duration="monthly",
    strategy="fixed",
)
print(spending_limit)
```

#### Response

```json
{
  "errors": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "messages": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "result": {},
  "success": true,
  "result_info": {
    "has_more": true,
    "page": 0,
    "per_page": 0,
    "total_count": 0
  }
}
```

## Delete spending limit

`ai_gateway.billing.spending_limit.delete(SpendingLimitDeleteParams**kwargs)  -> object`

**delete** `/accounts/{account_id}/ai-gateway/billing/spending-limit`

Remove the spending limit for the account.

### Parameters

- `account_id: str`

### Returns

- `object`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
spending_limit = client.ai_gateway.billing.spending_limit.delete(
    account_id="account_id",
)
print(spending_limit)
```

#### Response

```json
{
  "errors": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "messages": [
    {
      "code": 0,
      "message": "message"
    }
  ],
  "result": {},
  "success": true,
  "result_info": {
    "has_more": true,
    "page": 0,
    "per_page": 0,
    "total_count": 0
  }
}
```

## Domain Types

### Spending Limit Get Response

- `class SpendingLimitGetResponse: …`

  - `config: Config`

    - `amount: Optional[float]`

    - `duration: Optional[str]`

    - `strategy: Optional[str]`

  - `enabled: bool`