Billing API

The Billing API provides programmatic access to subscription management, capacity operations, and billing state queries. All billing endpoints require owner-level authorization.

Authentication

Billing endpoints accept:

Browser session — Cookie-based auth from the dashboard
Member token — Bearer token for CLI and automation

curl https://api.debugbundle.com/v1/billing \
  -H "Authorization: Bearer dbundle_mem_a1b2c3d4..."

Stripe Checkout and Customer Portal routes are browser-session-only.

Endpoints

Get Billing Summary

Returns the current billing state for the authenticated member's organization.

GET /v1/billing

Response:

{
  "billing": {
    "plan": "solo",
    "billing_state": "trialing",
    "stripe_customer_id": null,
    "active_projects": 4,
    "capacity_units": {
      "total": 3,
      "included": 3,
      "additional_purchased": 0,
      "pending_reduction": null
    },
    "usage_window": {
      "starts_at": "2025-01-01T00:00:00Z",
      "ends_at": "2025-02-01T00:00:00Z"
    },
    "allowances": {
      "monthly_bundle_requests": { "used": 120, "limit": 1500 },
      "monthly_raw_ingested_events": { "used": 820, "limit": 21000 },
      "retained_bundle_cap": { "used": 40, "limit": 900 },
      "monthly_remote_activations": { "used": 4, "limit": 150 },
      "monthly_alert_deliveries": { "used": 18, "limit": 450 },
      "monthly_webhook_deliveries": { "used": 40, "limit": 1500 }
    },
    "trial": {
      "available": false,
      "active": true,
      "plan": "solo",
      "started_at": "2025-01-02T00:00:00Z",
      "ends_at": "2025-02-01T00:00:00Z",
      "used_at": "2025-01-02T00:00:00Z",
      "converted_at": null,
      "expired_at": null,
      "days_remaining": 12
    }
  }
}

billing_state may be null, active, past_due, canceled, unpaid, incomplete, admin_override, trialing, or trial_expired. The trial object is always present.

When a capacity reduction is pending:

{
  "billing": {
    "capacity_units": {
      "pending_reduction": {
        "additional_purchased": 1,
        "total": 4,
        "effective_at": "2025-02-01T00:00:00Z"
      }
    }
  }
}

Start Checkout

Creates a Stripe Checkout Session for upgrading to a paid plan.

POST /v1/billing/checkout

Request:

{ "target_plan": "solo" }

Response:

{ "url": "https://checkout.stripe.com/c/pay/..." }

Start No-Card Trial

Starts an eligible 30-day no-card Solo or Team trial.

POST /v1/billing/trial/start

Request:

{ "target_plan": "team" }

Response:

Returns the standard billing summary response with the updated billing_state and trial fields.

Notes:

Only eligible Free organizations can start a trial
target_plan must be solo or team
Browser sessions and owner-scoped member tokens can both call this route

Open Customer Portal

Creates a Stripe Customer Portal session for managing payment methods and viewing invoices.

POST /v1/billing/portal

Response:

{ "url": "https://billing.stripe.com/p/session/..." }

Adds extra capacity units immediately with prorated billing. The target extra-capacity quantity must be greater than the current purchased quantity and no greater than 99. Active no-card trials receive 409 trial_conversion_required and must convert to paid first.

POST /v1/billing/capacity/increase

Request:

{ "target_additional_capacity_units": 5 }

Response:

{
  "billing": {
    "active_projects": 4,
    "capacity_units": {
      "total": 7,
      "included": 3,
      "additional_purchased": 5,
      "pending_reduction": null
    }
  }
}

Schedule Capacity Reduction

Schedules a capacity reduction for the next billing-period boundary. The target extra-capacity quantity must be lower than the current purchased quantity and no greater than 99. Active no-card trials receive 409 trial_conversion_required.

POST /v1/billing/capacity/scheduled-reduction

Request:

{ "target_additional_capacity_units": 1 }

Response:

{
  "billing": {
    "capacity_units": {
      "pending_reduction": {
        "additional_purchased": 1,
        "total": 4,
        "effective_at": "2025-02-01T00:00:00Z"
      }
    }
  }
}

Cancel Scheduled Capacity Reduction

Cancels a pending capacity reduction and returns the updated billing summary.

DELETE /v1/billing/capacity/scheduled-reduction

Active no-card trials receive 409 trial_conversion_required.

CLI Usage

# View billing summary
debugbundle billing get

# Start a no-card trial
debugbundle billing trial start --plan team

# Add capacity units
debugbundle billing capacity increase --target-additional-capacity-units 2

# Schedule capacity reduction
debugbundle billing capacity schedule-reduction --target-additional-capacity-units 3

# Cancel pending reduction
debugbundle billing capacity cancel-reduction

MCP Tools

All billing operations are available as MCP tools for AI agent workflows:

MCP Tool	Description
`get_billing_summary`	Get plan, billing state, trial state, active-project counts, capacity units, and scheduled changes
`start_trial`	Start an eligible no-card Solo or Team trial
`increase_capacity`	Add capacity units with prorated billing
`schedule_capacity_reduction`	Schedule a capacity reduction for the next billing cycle
`cancel_capacity_reduction`	Cancel a pending capacity reduction

See MCP Tools Reference for full parameter details.

Next Steps

Billing — How billing works
Pricing — Plan comparison
API Overview — API authentication and conventions

Billing API

Authentication

Endpoints

Get Billing Summary

Start Checkout

Start No-Card Trial

Open Customer Portal

Increase Capacity

Schedule Capacity Reduction

Cancel Scheduled Capacity Reduction

CLI Usage

MCP Tools

Next Steps

On this page