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.

GET /v1/account/{account_id}/billing-group

account_id · string · required

Account/organization ID

Request example

cURL

curl -X GET "https://api.aiven.io/v1/account/YOUR_ACCOUNT_ID/billing-group" \
  -H "Authorization: aivenv1 YOUR_TOKEN"

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']}")

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);

Response

billing_groups · array

List of billing group objects

Show child attributes

billing_group_id · string

Billing group identifier

billing_group_name · string

Billing group name

account_id · string

Account/organization ID

billing_currency · string

Currency code (e.g., USD, EUR)

billing_email · array

Email addresses for billing notifications

company · string

Company name

address_lines · array

Billing address lines

city · string

City

state · string

State/province

country_code · string

Two-letter country code

zip_code · string

Postal/ZIP code

vat_id · string

VAT identification number

payment_method · string

Payment method type: card, paypal, partner

Response example

{
  "billing_groups": [
    {
      "billing_group_id": "588a8e63-fda7-4ff7-9bff-577debfee604",
      "billing_group_name": "Production",
      "account_id": "a225dad8d3c4",
      "billing_currency": "USD",
      "billing_email": ["[e-mail]"],
      "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.

GET /v1/billing-group/{billing_group_id}

billing_group_id · string · required

Billing group ID

Request example

cURL

curl -X GET "https://api.aiven.io/v1/billing-group/588a8e63-fda7-4ff7-9bff-577debfee604" \
  -H "Authorization: aivenv1 YOUR_TOKEN"

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'])}")

Response

billing_group · object

Detailed billing group information including assigned projects

Show child attributes

projects · array

List of projects assigned to this billing group

card_info · object

Credit card information (if applicable)

Create billing group

Create a new billing group in your organization.

POST /v1/account/{account_id}/billing-group

account_id · string · required

Account/organization ID

Request body

billing_group_name · string · required

Name for the billing group

billing_currency · string

Currency code (e.g., USD, EUR, GBP)

company · string

Company name

billing_email · array

Email addresses for billing notifications

address_lines · array

Billing address lines

city · string

City

state · string

State/province

country_code · string

Two-letter country code

zip_code · string

Postal/ZIP code

vat_id · string

VAT identification number

Request example

cURL

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": ["[e-mail]"],
    "city": "San Francisco",
    "country_code": "US"
  }'

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": ["[e-mail]"],
    "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']}")

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: ['[e-mail]'],
      city: 'San Francisco',
      country_code: 'US'
    })
  }
);

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

Response

billing_group · object

The newly created billing group object

Update billing group

Update billing group information.

PUT /v1/billing-group/{billing_group_id}

billing_group_id · string · required

Billing group ID

Request body

Accepts the same fields as create billing group.

Request example

cURL

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": ["[e-mail]", "[e-mail]"],
    "vat_id": "GB123456789"
  }'

import requests

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

data = {
    "billing_email": ["[e-mail]", "[e-mail]"],
    "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")

Response

billing_group · object

The updated billing group object

Assign project to billing group

Assign a project to a specific billing group.

PUT /v1/project/{project}

project · string · required

Project name

Request body

billing_group_id · string · required

Billing group ID to assign the project to

Request example

cURL

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"
  }'

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}")

List invoices

Retrieve invoices for a billing group.

GET /v1/billing-group/{billing_group_id}/invoice

billing_group_id · string · required

Billing group ID

Request example

cURL

curl -X GET "https://api.aiven.io/v1/billing-group/588a8e63-fda7-4ff7-9bff-577debfee604/invoice" \
  -H "Authorization: aivenv1 YOUR_TOKEN"

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']})")

Response

invoices · array

List of invoice objects

Show child attributes

invoice_number · string

Invoice number

period_begin · string

Billing period start date (ISO 8601)

period_end · string

Billing period end date (ISO 8601)

state · string

Invoice state: unpaid, paid, void, uncollectible

currency · string

Currency code

total_inc_vat · string

Total amount including VAT

total_vat_zero · string

Total amount excluding VAT

download_url · string

URL to download invoice PDF

Response example

{
  "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.

GET /v1/project/{project}/estimate

project · string · required

Project name

Request example

cURL

curl -X GET "https://api.aiven.io/v1/project/my-project/estimate" \
  -H "Authorization: aivenv1 YOUR_TOKEN"

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']}")

Response

estimated_balance · string

Estimated balance for the current billing period

billing_currency · string

Currency code

services · array

Per-service cost breakdown

Response example

{
  "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.

GET /v1/account/{account_id}/credits

account_id · string · required

Account/organization ID

Request example

cURL

curl -X GET "https://api.aiven.io/v1/account/YOUR_ACCOUNT_ID/credits" \
  -H "Authorization: aivenv1 YOUR_TOKEN"

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']}")

Response

available_credits · string

Currently available credits

total_credits · string

Total credits received

currency · string

Currency code

Related resources

• Manage billing groups in Console
• Billing concepts
• Projects API
• Full API reference