Add details on billing

docs.json

@@ -107,6 +107,15 @@
           {
             "group": "Net Diagnostics",
             "pages": ["iroh-services/net-diagnostics/quickstart", "iroh-services/net-diagnostics/usage", "iroh-services/net-diagnostics/reports"]
+          },
+          {
+            "group": "Billing",
+            "pages": [
+              "iroh-services/billing/index",
+              "iroh-services/billing/manage-subscription",
+              "iroh-services/billing/control-costs",
+              "iroh-services/billing/faq"
+            ]
           }
         ]
       }

iroh-services/billing/control-costs.mdx

@@ -0,0 +1,38 @@
+---
+title: "Control Your Costs"
+description: "Set spend caps and monitor usage to keep your Iroh Services costs predictable"
+---
+
+Iroh Services provides tools to help you stay in control of your spending.
+
+## Spend caps
+
+Spend caps let you set a maximum monthly budget for your project. When your usage reaches the cap, services that incur additional charges will be paused until the next billing cycle.
+
+### Setting a spend cap
+
+1. Go to your project dashboard.
+2. Navigate to **Settings**
+3. Under **Spend cap**, enter your maximum monthly budget.
+4. Click **Save**.
+
+<Note>
+Your spend cap applies to your total invoice, including the base plan cost, any applicable taxes, and usage-based charges that exceed what's included in your plan.
+</Note>
+
+### What happens when you hit your cap
+
+When your usage-based charges reach your spend cap:
+
+- **Metrics ingestion** will be paused. Endpoints will stop sending new metrics until the next billing cycle.
+- **Your existing data** is preserved. Dashboards and historical metrics remain accessible.
+- **Endpoint connections** — the number of active connections sending metrics to your project will be throttled.
+- **Active relay connections** are not affected. Your endpoints will continue to connect through relays.
+
+Usage resets at the start of each billing cycle.
+
+## Tips for managing costs
+
+- **Start with the Free plan** to understand your usage patterns before upgrading.
+- **Set a spend cap** early to avoid unexpected charges.
+- **Review usage regularly** from the dashboard to spot trends before they become costly.

iroh-services/billing/faq.mdx

@@ -0,0 +1,51 @@
+---
+title: "Billing FAQ"
+description: "Frequently asked questions about Iroh Services billing"
+---
+
+## What payment methods do you accept?
+
+We accept major credit and debit cards. Payment is processed securely through our payment provider.
+
+## When am I billed?
+
+Billing is monthly. You'll be charged at the beginning of each billing cycle for
+your plan, and at the end of the cycle for any usage-based overages.
+
+## Can I try Iroh Services for free?
+
+Yes. The Free plan gives you access to shared public relays, basic metrics, and
+community support on Discord at no cost.
+
+## What happens if my payment fails?
+
+If a payment fails, we'll retry a few times and notify you by email. If the
+issue isn't resolved, your project may be downgraded to the Free plan.
+
+## Do I get a refund if I cancel mid-cycle?
+
+Relays are billed based on hourly usage, so you'll only be charged for the hours
+you used. For example, if you cancel after 10 hours of relay usage in a month,
+you'll only be billed for those 10 hours. If you have any
+questions about your bill or refunds, please contact us at [support@iroh.computer](mailto:support@iroh.computer).
+
+## How do spend caps work?
+
+Spend caps limit your usage-based charges (not your base plan cost). When you
+hit your cap, usage-based services like metrics ingestion are paused until the
+next cycle. See [Control your costs](/iroh-services/billing/control-costs) for
+details.
+
+## Where can I see my invoices?
+
+Invoices are available in the **Settings** > **Billing** section of your
+[project dashboard](https://n0des.iroh.computer).
+
+## Are taxes included in the prices?
+
+Prices shown do not include taxes. Applicable taxes (such as VAT or sales tax) 
+may or may not be added at checkout based on your billing address and your local tax rules.
+
+## I have a billing question not listed here
+
+Reach out to us at [support@iroh.computer](mailto:support@iroh.computer).

iroh-services/billing/index.mdx

@@ -0,0 +1,32 @@
+---
+title: "Overview"
+description: "Understand how billing works for Iroh Services"
+---
+
+Iroh Services offers plans to fit your needs, from free tiers for experimentation to enterprise plans for production workloads.
+
+## Plans
+
+| | **Free** | **Pro** | **Enterprise** |
+|---|---|---|---|
+| **Relays** | Shared public relays | Managed dedicated relays | Custom relay configurations |
+| **Metrics** | 1 day retention | 7 day retention | Custom retention & SLAs |
+| **Net Diagnostics** | Community support | Priority support tickets | Guaranteed SLA response times |
+| **Support** | Discord | Email & Discord | Dedicated support & professional services |
+
+For full plan details and pricing, visit the [pricing page](https://n0des.iroh.computer/pricing).
+
+## How billing works
+
+Iroh Services billing is usage-based, calculated monthly. Your bill is determined by:
+
+- **Your plan tier** — each plan includes a base set of features and resource allocations.
+- **Resource usage** — additional charges may apply for usage beyond what's included in your plan, such as metrics volume or relay bandwidth.
+
+Billing is managed through the [Iroh Services dashboard](https://n0des.iroh.computer). You can view your current plan, usage, and invoices at any time.
+
+## Next steps
+
+- [Manage your subscription](/iroh-services/billing/manage-subscription) — upgrade, downgrade, or cancel your plan.
+- [Control your costs](/iroh-services/billing/control-costs) — set spend caps and monitor usage.
+- [Billing FAQ](/iroh-services/billing/faq) — common questions about billing and payments.

iroh-services/billing/manage-subscription.mdx

@@ -0,0 +1,58 @@
+---
+title: "Manage Your Subscription"
+description: "Upgrade, downgrade, or cancel your Iroh Services subscription"
+---
+
+Manage your subscription from the [Iroh Services dashboard](https://n0des.iroh.computer).
+
+## Upgrade your plan
+
+1. Go to your project dashboard.
+2. Navigate to **Settings** > **Billing**.
+3. Select the plan you'd like to upgrade to.
+4. Confirm the change.
+
+Upgrades take effect immediately.
+
+## Remove relays
+
+Relays are charged to your account per hour of usage. To avoid unnecessary
+costs, make sure to remove any custom relays that you no longer need.
+
+1. Go to your project dashboard.
+2. Navigate to **Relays**.
+3. Click the three dot menu next to any custom relay to remove it.
+
+
+## Downgrade your plan
+
+In order to downgrade from Pro to Free, you need to remove any custom relays first. 
+
+1. Go to your project dashboard.
+2. Navigate to **Settings** > **Billing**.
+3. Select a lower-tier plan.
+4. Confirm the change.
+
+
+## Cancel your subscription
+
+After cancellation, your data will be retained according to the Free plan's
+retention policy. There is no immediate deletion of data upon cancellation, but
+you will lose access to any features that are not included in the Free plan. If
+you decide to re-subscribe in the future, your data may still be accessible, but
+we cannot guarantee its availability because data cleanup may have occurred.
+
+1. Go to your project dashboard.
+2. Navigate to **Settings** > **Billing**.
+3. Click **Cancel subscription**.
+
+
+## Update payment method
+
+1. Go to your project dashboard.
+2. Navigate to **Settings** > **Billing**.
+3. Click **Payment method** to add or update your card on file.
+
+## Invoices
+
+Invoices are generated monthly and available in the **Billing** section of your dashboard. You can download past invoices at any time.