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

# Billing and Payment

> Manage billing groups, payment methods, and invoices via the REST API

Manage billing information, payment methods, and invoices for your Aiven organization. Billing groups allow you to organize costs across multiple projects.

## List billing groups

Retrieve all billing groups in your organization.

```http theme={null}
GET /v1/account/{account_id}/billing-group
```

<ParamField path="account_id" type="string" required>
  Account/organization ID
</ParamField>

### Request example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.aiven.io/v1/account/YOUR_ACCOUNT_ID/billing-group" \
    -H "Authorization: aivenv1 YOUR_TOKEN"
  ```

  ```python Python theme={null}
  import requests

  account_id = "YOUR_ACCOUNT_ID"
  headers = {"Authorization": "aivenv1 YOUR_TOKEN"}

  response = requests.get(
      f"https://api.aiven.io/v1/account/{account_id}/billing-group",
      headers=headers
  )

  billing_groups = response.json()["billing_groups"]
  for group in billing_groups:
      print(f"{group['billing_group_name']}: {group['billing_currency']}")
  ```

  ```javascript JavaScript theme={null}
  const accountId = 'YOUR_ACCOUNT_ID';
  const response = await fetch(
    `https://api.aiven.io/v1/account/${accountId}/billing-group`,
    {
      headers: {
        'Authorization': 'aivenv1 YOUR_TOKEN'
      }
    }
  );

  const data = await response.json();
  console.log(data.billing_groups);
  ```
</CodeGroup>

### Response

<ResponseField name="billing_groups" type="array">
  List of billing group objects

  <Expandable>
    <ResponseField name="billing_group_id" type="string">
      Billing group identifier
    </ResponseField>

    <ResponseField name="billing_group_name" type="string">
      Billing group name
    </ResponseField>

    <ResponseField name="account_id" type="string">
      Account/organization ID
    </ResponseField>

    <ResponseField name="billing_currency" type="string">
      Currency code (e.g., `USD`, `EUR`)
    </ResponseField>

    <ResponseField name="billing_email" type="array">
      Email addresses for billing notifications
    </ResponseField>

    <ResponseField name="company" type="string">
      Company name
    </ResponseField>

    <ResponseField name="address_lines" type="array">
      Billing address lines
    </ResponseField>

    <ResponseField name="city" type="string">
      City
    </ResponseField>

    <ResponseField name="state" type="string">
      State/province
    </ResponseField>

    <ResponseField name="country_code" type="string">
      Two-letter country code
    </ResponseField>

    <ResponseField name="zip_code" type="string">
      Postal/ZIP code
    </ResponseField>

    <ResponseField name="vat_id" type="string">
      VAT identification number
    </ResponseField>

    <ResponseField name="payment_method" type="string">
      Payment method type: `card`, `paypal`, `partner`
    </ResponseField>
  </Expandable>
</ResponseField>

### Response example

```json theme={null}
{
  "billing_groups": [
    {
      "billing_group_id": "588a8e63-fda7-4ff7-9bff-577debfee604",
      "billing_group_name": "Production",
      "account_id": "a225dad8d3c4",
      "billing_currency": "USD",
      "billing_email": ["billing@example.com"],
      "company": "Example Inc",
      "address_lines": ["123 Main St"],
      "city": "San Francisco",
      "state": "CA",
      "country_code": "US",
      "zip_code": "94102",
      "vat_id": "",
      "payment_method": "card"
    }
  ]
}
```

## Get billing group details

Retrieve detailed information about a specific billing group.

```http theme={null}
GET /v1/billing-group/{billing_group_id}
```

<ParamField path="billing_group_id" type="string" required>
  Billing group ID
</ParamField>

### Request example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.aiven.io/v1/billing-group/588a8e63-fda7-4ff7-9bff-577debfee604" \
    -H "Authorization: aivenv1 YOUR_TOKEN"
  ```

  ```python Python theme={null}
  import requests

  billing_group_id = "588a8e63-fda7-4ff7-9bff-577debfee604"
  headers = {"Authorization": "aivenv1 YOUR_TOKEN"}

  response = requests.get(
      f"https://api.aiven.io/v1/billing-group/{billing_group_id}",
      headers=headers
  )

  group = response.json()["billing_group"]
  print(f"Billing Group: {group['billing_group_name']}")
  print(f"Currency: {group['billing_currency']}")
  print(f"Projects: {len(group['projects'])}")
  ```
</CodeGroup>

### Response

<ResponseField name="billing_group" type="object">
  Detailed billing group information including assigned projects

  <Expandable>
    <ResponseField name="projects" type="array">
      List of projects assigned to this billing group
    </ResponseField>

    <ResponseField name="card_info" type="object">
      Credit card information (if applicable)
    </ResponseField>
  </Expandable>
</ResponseField>

## Create billing group

Create a new billing group in your organization.

```http theme={null}
POST /v1/account/{account_id}/billing-group
```

<ParamField path="account_id" type="string" required>
  Account/organization ID
</ParamField>

### Request body

<ParamField body="billing_group_name" type="string" required>
  Name for the billing group
</ParamField>

<ParamField body="billing_currency" type="string">
  Currency code (e.g., `USD`, `EUR`, `GBP`)
</ParamField>

<ParamField body="company" type="string">
  Company name
</ParamField>

<ParamField body="billing_email" type="array">
  Email addresses for billing notifications
</ParamField>

<ParamField body="address_lines" type="array">
  Billing address lines
</ParamField>

<ParamField body="city" type="string">
  City
</ParamField>

<ParamField body="state" type="string">
  State/province
</ParamField>

<ParamField body="country_code" type="string">
  Two-letter country code
</ParamField>

<ParamField body="zip_code" type="string">
  Postal/ZIP code
</ParamField>

<ParamField body="vat_id" type="string">
  VAT identification number
</ParamField>

### Request example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.aiven.io/v1/account/YOUR_ACCOUNT_ID/billing-group" \
    -H "Authorization: aivenv1 YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "billing_group_name": "Development Team",
      "billing_currency": "USD",
      "company": "Example Inc",
      "billing_email": ["billing@example.com"],
      "city": "San Francisco",
      "country_code": "US"
    }'
  ```

  ```python Python theme={null}
  import requests

  account_id = "YOUR_ACCOUNT_ID"
  headers = {
      "Authorization": "aivenv1 YOUR_TOKEN",
      "Content-Type": "application/json"
  }

  data = {
      "billing_group_name": "Development Team",
      "billing_currency": "USD",
      "company": "Example Inc",
      "billing_email": ["billing@example.com"],
      "city": "San Francisco",
      "country_code": "US"
  }

  response = requests.post(
      f"https://api.aiven.io/v1/account/{account_id}/billing-group",
      headers=headers,
      json=data
  )

  billing_group = response.json()["billing_group"]
  print(f"Created billing group: {billing_group['billing_group_name']}")
  print(f"ID: {billing_group['billing_group_id']}")
  ```

  ```javascript JavaScript theme={null}
  const accountId = 'YOUR_ACCOUNT_ID';
  const response = await fetch(
    `https://api.aiven.io/v1/account/${accountId}/billing-group`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'aivenv1 YOUR_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        billing_group_name: 'Development Team',
        billing_currency: 'USD',
        company: 'Example Inc',
        billing_email: ['billing@example.com'],
        city: 'San Francisco',
        country_code: 'US'
      })
    }
  );

  const data = await response.json();
  console.log('Created billing group:', data.billing_group.billing_group_id);
  ```
</CodeGroup>

### Response

<ResponseField name="billing_group" type="object">
  The newly created billing group object
</ResponseField>

## Update billing group

Update billing group information.

```http theme={null}
PUT /v1/billing-group/{billing_group_id}
```

<ParamField path="billing_group_id" type="string" required>
  Billing group ID
</ParamField>

### Request body

Accepts the same fields as create billing group.

### Request example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.aiven.io/v1/billing-group/588a8e63-fda7-4ff7-9bff-577debfee604" \
    -H "Authorization: aivenv1 YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "billing_email": ["billing@example.com", "finance@example.com"],
      "vat_id": "GB123456789"
    }'
  ```

  ```python Python theme={null}
  import requests

  billing_group_id = "588a8e63-fda7-4ff7-9bff-577debfee604"
  headers = {
      "Authorization": "aivenv1 YOUR_TOKEN",
      "Content-Type": "application/json"
  }

  data = {
      "billing_email": ["billing@example.com", "finance@example.com"],
      "vat_id": "GB123456789"
  }

  response = requests.put(
      f"https://api.aiven.io/v1/billing-group/{billing_group_id}",
      headers=headers,
      json=data
  )

  print("Updated billing group successfully")
  ```
</CodeGroup>

### Response

<ResponseField name="billing_group" type="object">
  The updated billing group object
</ResponseField>

## Assign project to billing group

Assign a project to a specific billing group.

```http theme={null}
PUT /v1/project/{project}
```

<ParamField path="project" type="string" required>
  Project name
</ParamField>

### Request body

<ParamField body="billing_group_id" type="string" required>
  Billing group ID to assign the project to
</ParamField>

### Request example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.aiven.io/v1/project/my-project" \
    -H "Authorization: aivenv1 YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "billing_group_id": "588a8e63-fda7-4ff7-9bff-577debfee604"
    }'
  ```

  ```python Python theme={null}
  import requests

  project = "my-project"
  billing_group_id = "588a8e63-fda7-4ff7-9bff-577debfee604"

  headers = {
      "Authorization": "aivenv1 YOUR_TOKEN",
      "Content-Type": "application/json"
  }

  data = {
      "billing_group_id": billing_group_id
  }

  response = requests.put(
      f"https://api.aiven.io/v1/project/{project}",
      headers=headers,
      json=data
  )

  print(f"Project {project} assigned to billing group {billing_group_id}")
  ```
</CodeGroup>

## List invoices

Retrieve invoices for a billing group.

```http theme={null}
GET /v1/billing-group/{billing_group_id}/invoice
```

<ParamField path="billing_group_id" type="string" required>
  Billing group ID
</ParamField>

### Request example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.aiven.io/v1/billing-group/588a8e63-fda7-4ff7-9bff-577debfee604/invoice" \
    -H "Authorization: aivenv1 YOUR_TOKEN"
  ```

  ```python Python theme={null}
  import requests

  billing_group_id = "588a8e63-fda7-4ff7-9bff-577debfee604"
  headers = {"Authorization": "aivenv1 YOUR_TOKEN"}

  response = requests.get(
      f"https://api.aiven.io/v1/billing-group/{billing_group_id}/invoice",
      headers=headers
  )

  invoices = response.json()["invoices"]
  for invoice in invoices:
      print(f"Invoice {invoice['invoice_number']}: ${invoice['total_inc_vat']} ({invoice['state']})")
  ```
</CodeGroup>

### Response

<ResponseField name="invoices" type="array">
  List of invoice objects

  <Expandable>
    <ResponseField name="invoice_number" type="string">
      Invoice number
    </ResponseField>

    <ResponseField name="period_begin" type="string">
      Billing period start date (ISO 8601)
    </ResponseField>

    <ResponseField name="period_end" type="string">
      Billing period end date (ISO 8601)
    </ResponseField>

    <ResponseField name="state" type="string">
      Invoice state: `unpaid`, `paid`, `void`, `uncollectible`
    </ResponseField>

    <ResponseField name="currency" type="string">
      Currency code
    </ResponseField>

    <ResponseField name="total_inc_vat" type="string">
      Total amount including VAT
    </ResponseField>

    <ResponseField name="total_vat_zero" type="string">
      Total amount excluding VAT
    </ResponseField>

    <ResponseField name="download_url" type="string">
      URL to download invoice PDF
    </ResponseField>
  </Expandable>
</ResponseField>

### Response example

```json theme={null}
{
  "invoices": [
    {
      "invoice_number": "INV-2024-001234",
      "period_begin": "2024-02-01T00:00:00Z",
      "period_end": "2024-02-29T23:59:59Z",
      "state": "paid",
      "currency": "USD",
      "total_inc_vat": "1234.56",
      "total_vat_zero": "1234.56",
      "download_url": "https://api.aiven.io/v1/invoice/INV-2024-001234/download"
    }
  ]
}
```

## Get estimated costs

Retrieve current month's estimated costs for a project.

```http theme={null}
GET /v1/project/{project}/estimate
```

<ParamField path="project" type="string" required>
  Project name
</ParamField>

### Request example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.aiven.io/v1/project/my-project/estimate" \
    -H "Authorization: aivenv1 YOUR_TOKEN"
  ```

  ```python Python theme={null}
  import requests

  project = "my-project"
  headers = {"Authorization": "aivenv1 YOUR_TOKEN"}

  response = requests.get(
      f"https://api.aiven.io/v1/project/{project}/estimate",
      headers=headers
  )

  estimate = response.json()
  print(f"Estimated costs for {project}:")
  print(f"Total: ${estimate['estimated_balance']}")
  print(f"Currency: {estimate['billing_currency']}")
  ```
</CodeGroup>

### Response

<ResponseField name="estimated_balance" type="string">
  Estimated balance for the current billing period
</ResponseField>

<ResponseField name="billing_currency" type="string">
  Currency code
</ResponseField>

<ResponseField name="services" type="array">
  Per-service cost breakdown
</ResponseField>

### Response example

```json theme={null}
{
  "estimated_balance": "123.45",
  "billing_currency": "USD",
  "services": [
    {
      "service_name": "pg-demo",
      "service_type": "pg",
      "estimated_cost": "45.67"
    },
    {
      "service_name": "kafka-prod",
      "service_type": "kafka",
      "estimated_cost": "77.78"
    }
  ]
}
```

## Available credits

Check available credits for an account.

```http theme={null}
GET /v1/account/{account_id}/credits
```

<ParamField path="account_id" type="string" required>
  Account/organization ID
</ParamField>

### Request example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.aiven.io/v1/account/YOUR_ACCOUNT_ID/credits" \
    -H "Authorization: aivenv1 YOUR_TOKEN"
  ```

  ```python Python theme={null}
  import requests

  account_id = "YOUR_ACCOUNT_ID"
  headers = {"Authorization": "aivenv1 YOUR_TOKEN"}

  response = requests.get(
      f"https://api.aiven.io/v1/account/{account_id}/credits",
      headers=headers
  )

  credits = response.json()
  print(f"Available credits: ${credits['available_credits']}")
  print(f"Total credits: ${credits['total_credits']}")
  ```
</CodeGroup>

### Response

<ResponseField name="available_credits" type="string">
  Currently available credits
</ResponseField>

<ResponseField name="total_credits" type="string">
  Total credits received
</ResponseField>

<ResponseField name="currency" type="string">
  Currency code
</ResponseField>

## Related resources

* [Manage billing groups in Console](/platform/overview)
* [Billing concepts](/platform/authentication)
* [Projects API](/api-reference/projects)
* [Full API reference](https://api.aiven.io/doc/)