Overview

The Billing API provides access to your billing information, including current charges, payment history, and invoice details.

Required scope: billing:read

Endpoints

Method	Endpoint	Description
`GET`	`/v1/billing/summary`	Get current billing summary
`GET`	`/v1/billing/history`	Get billing history

Get Billing Summary

Retrieve a summary of your current billing period:

curl https://api.dnscale.eu/v1/billing/summary \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "status": "success",
  "data": {
    "customer_id": "cust_abc123",
    "plan": {
      "id": "plan_pro",
      "name": "Pro",
      "base_price": 29.00,
      "currency": "EUR"
    },
    "current_period": {
      "start": "2025-01-01T00:00:00Z",
      "end": "2025-01-31T23:59:59Z"
    },
    "charges": {
      "base": 29.00,
      "overage_queries": 0.00,
      "overage_zones": 0.00,
      "total": 29.00,
      "currency": "EUR"
    },
    "usage": {
      "queries": 25000000,
      "queries_included": 50000000,
      "zones": 45,
      "zones_included": 100
    }
  }
}

Get Billing History

Retrieve past invoices and payment history:

curl "https://api.dnscale.eu/v1/billing/history?limit=12" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters:

Parameter	Default	Description
`limit`	10	Number of records to return (max: 100)
`offset`	0	Records to skip

Response:

{
  "status": "success",
  "data": {
    "items": [
      {
        "id": "inv_abc123",
        "period": "2024-12",
        "status": "paid",
        "amount": 29.00,
        "currency": "EUR",
        "paid_at": "2025-01-01T00:00:00Z",
        "invoice_url": "https://billing.dnscale.eu/invoices/inv_abc123"
      },
      {
        "id": "inv_xyz789",
        "period": "2024-11",
        "status": "paid",
        "amount": 29.00,
        "currency": "EUR",
        "paid_at": "2024-12-01T00:00:00Z",
        "invoice_url": "https://billing.dnscale.eu/invoices/inv_xyz789"
      }
    ],
    "total": 12,
    "limit": 12,
    "offset": 0
  }
}

Billing Fields

Plan Information

Field	Description
`plan.id`	Plan identifier
`plan.name`	Plan display name
`plan.base_price`	Monthly base price
`plan.currency`	Price currency (EUR)

Charges Breakdown

Field	Description
`charges.base`	Monthly plan fee
`charges.overage_queries`	Charges for queries exceeding plan limit
`charges.overage_zones`	Charges for zones exceeding plan limit
`charges.total`	Total amount due

Invoice Status

Status	Description
`draft`	Invoice not yet finalized
`open`	Invoice awaiting payment
`paid`	Invoice paid successfully
`void`	Invoice cancelled
`uncollectible`	Payment failed

Pricing

Pricing matches the public pricing page (EUR, VAT excluded). Paid plans include a 7‑day free trial. Annual billing is available with two months free.

Plans (monthly)

Plan	Monthly Price	Included Queries	Included Zones	Records	Overage
Nano Free	€0	1,000,000	1	15	No overage (plan cannot exceed query limits)
Nano	€4.95	5,000,000	5	150	€0.20 per extra 1M queries
Pro	€24.95	25,000,000	25	1,500	€0.10 per extra 1M queries
Scale	€259.95	1,500,000,000	250	15,000	€0.10 per extra 1M queries
Enterprise	Custom	Custom	Custom	Custom	Tailored pricing and SLAs

Example: Estimate Monthly Cost

#!/bin/bash
# Estimate your monthly cost based on current usage
 
BILLING=$(curl -s https://api.dnscale.eu/v1/billing/summary \
  -H "Authorization: Bearer YOUR_API_KEY")
 
BASE=$(echo $BILLING | jq '.data.charges.base')
OVERAGE_QUERIES=$(echo $BILLING | jq '.data.charges.overage_queries')
OVERAGE_ZONES=$(echo $BILLING | jq '.data.charges.overage_zones')
TOTAL=$(echo $BILLING | jq '.data.charges.total')
 
echo "Billing Summary"
echo "==============="
echo "Base plan:        €$BASE"
echo "Query overage:    €$OVERAGE_QUERIES"
echo "Zone overage:     €$OVERAGE_ZONES"
echo "---------------"
echo "Total:            €$TOTAL"

Payment Methods

Manage payment methods via the DNScale dashboard:

Navigate to Settings → Billing
Click Payment Methods
Add or update your card details

DNScale accepts major credit cards (Visa, Mastercard, American Express) and processes payments securely via Stripe.

Invoices

Download PDF invoices from the billing history or use the invoice_url field:

# Get invoice URL
curl -s https://api.dnscale.eu/v1/billing/history?limit=1 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  | jq -r '.data.items[0].invoice_url'