Billing API

Manage subscriptions, usage, and invoices via the API.

Get Subscription

GET /v1/billing/subscription

Response:

{
  "data": {
    "id": "sub_abc123",
    "plan": "pro",
    "status": "active",
    "billing_cycle": "monthly",
    "current_period": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-31T23:59:59Z"
    },
    "payment_method": {
      "type": "card",
      "last4": "4242",
      "brand": "visa",
      "exp_month": 12,
      "exp_year": 2025
    },
    "next_invoice": {
      "amount_cents": 9900,
      "currency": "usd",
      "due_date": "2024-02-01T00:00:00Z"
    },
    "created_at": "2024-01-01T00:00:00Z"
  }
}

List Plans

GET /v1/billing/plans

Response:

{
  "data": [
    {
      "id": "plan_free",
      "name": "Free",
      "price_monthly_cents": 0,
      "price_yearly_cents": 0,
      "features": {
        "namespaces": 1,
        "databases": 1,
        "storage_gb": 5,
        "bandwidth_gb": 10,
        "support": "community"
      }
    },
    {
      "id": "plan_starter",
      "name": "Starter",
      "price_monthly_cents": 2900,
      "price_yearly_cents": 29000,
      "features": {
        "namespaces": 5,
        "databases": 5,
        "storage_gb": 50,
        "bandwidth_gb": 100,
        "support": "email"
      }
    },
    {
      "id": "plan_pro",
      "name": "Pro",
      "price_monthly_cents": 9900,
      "price_yearly_cents": 99000,
      "features": {
        "namespaces": 25,
        "databases": 25,
        "storage_gb": 500,
        "bandwidth_gb": 1000,
        "support": "priority"
      }
    },
    {
      "id": "plan_enterprise",
      "name": "Enterprise",
      "price_monthly_cents": null,
      "price_yearly_cents": null,
      "features": {
        "namespaces": "unlimited",
        "databases": "unlimited",
        "storage_gb": "unlimited",
        "bandwidth_gb": "unlimited",
        "support": "dedicated"
      }
    }
  ]
}

Change Plan

POST /v1/billing/subscription

Request Body:

{
  "plan": "pro",
  "billing_cycle": "yearly"
}

Response:

{
  "data": {
    "id": "sub_abc123",
    "plan": "pro",
    "status": "active",
    "billing_cycle": "yearly",
    "change_effective": "2024-02-01T00:00:00Z"
  }
}

Cancel Subscription

DELETE /v1/billing/subscription

Request Body (optional):

{
  "cancel_at_period_end": true,
  "feedback": "switching_to_competitor"
}

Response:

{
  "data": {
    "id": "sub_abc123",
    "status": "canceling",
    "cancel_at": "2024-01-31T23:59:59Z"
  }
}

Usage

Get Current Usage

GET /v1/billing/usage

Response:

{
  "data": {
    "period": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-31T23:59:59Z"
    },
    "resources": {
      "namespaces": {
        "count": 5,
        "limit": 25
      },
      "databases": {
        "count": 3,
        "limit": 25
      },
      "storage": {
        "used_gb": 45.5,
        "limit_gb": 500
      },
      "bandwidth": {
        "used_gb": 125.3,
        "limit_gb": 1000
      },
      "compute": {
        "cpu_hours": 720,
        "memory_gb_hours": 1440
      }
    },
    "metered_charges": [
      {
        "description": "Additional bandwidth",
        "quantity": 25.3,
        "unit": "GB",
        "unit_price_cents": 10,
        "total_cents": 253
      }
    ],
    "estimated_total_cents": 9900
  }
}

Get Usage History

GET /v1/billing/usage/history

Query Parameters:

Parameter	Type	Description
start_date	string	Start date (YYYY-MM-DD)
end_date	string	End date (YYYY-MM-DD)
granularity	string	daily, weekly, monthly (default: daily)

Response:

{
  "data": [
    {
      "date": "2024-01-01",
      "compute_hours": 24,
      "storage_gb": 40.2,
      "bandwidth_gb": 5.1,
      "api_requests": 15000
    },
    {
      "date": "2024-01-02",
      "compute_hours": 24,
      "storage_gb": 41.5,
      "bandwidth_gb": 4.8,
      "api_requests": 14500
    }
  ]
}

Invoices

List Invoices

GET /v1/billing/invoices

Response:

{
  "data": [
    {
      "id": "inv_abc123",
      "number": "INV-2024-001",
      "status": "paid",
      "amount_cents": 9900,
      "currency": "usd",
      "period": {
        "start": "2024-01-01T00:00:00Z",
        "end": "2024-01-31T23:59:59Z"
      },
      "paid_at": "2024-01-01T00:00:00Z",
      "pdf_url": "https://billing.sparbz.cloud/invoices/inv_abc123.pdf",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "per_page": 20
  }
}

Get Invoice

GET /v1/billing/invoices/:id

Response:

{
  "data": {
    "id": "inv_abc123",
    "number": "INV-2024-001",
    "status": "paid",
    "amount_cents": 9900,
    "currency": "usd",
    "line_items": [
      {
        "description": "Pro Plan - Monthly",
        "quantity": 1,
        "unit_price_cents": 9900,
        "amount_cents": 9900
      }
    ],
    "subtotal_cents": 9900,
    "tax_cents": 0,
    "total_cents": 9900,
    "period": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-31T23:59:59Z"
    },
    "payment_method": {
      "type": "card",
      "last4": "4242",
      "brand": "visa"
    },
    "paid_at": "2024-01-01T00:00:00Z",
    "pdf_url": "https://billing.sparbz.cloud/invoices/inv_abc123.pdf"
  }
}

Download Invoice PDF

GET /v1/billing/invoices/:id/pdf

Response: PDF file download

Payment Methods

List Payment Methods

GET /v1/billing/payment-methods

Response:

{
  "data": [
    {
      "id": "pm_abc123",
      "type": "card",
      "is_default": true,
      "card": {
        "brand": "visa",
        "last4": "4242",
        "exp_month": 12,
        "exp_year": 2025
      },
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Add Payment Method

POST /v1/billing/payment-methods

Request Body:

{
  "payment_method_id": "pm_stripe_token",
  "set_default": true
}

Remove Payment Method

DELETE /v1/billing/payment-methods/:id

Response: 204 No Content

Billing Portal

Create Portal Session

POST /v1/billing/portal

Creates a Stripe Billing Portal session for self-service billing management.

Response:

{
  "data": {
    "url": "https://billing.stripe.com/session/...",
    "expires_at": "2024-01-15T11:30:00Z"
  }
}

Quotas

Get Quotas

GET /v1/billing/quotas

Response:

{
  "data": {
    "plan": "pro",
    "quotas": {
      "namespaces": {
        "limit": 25,
        "used": 5,
        "available": 20
      },
      "databases": {
        "limit": 25,
        "used": 3,
        "available": 22
      },
      "storage_gb": {
        "limit": 500,
        "used": 45.5,
        "available": 454.5
      },
      "members": {
        "limit": 25,
        "used": 12,
        "available": 13
      }
    }
  }
}