# Billing & Pricing

How HivePay charges merchants — monthly billing on processed volume, with a tiered rate schedule.

---

## How It Works

HivePay uses a **monthly SaaS billing model**. Customer payments flow directly to your Hive account in a single transfer — HivePay does not deduct anything from individual transactions. At the end of each calendar month, HivePay generates a single invoice based on your total processed USD volume for that month.

| Component | Description |
|-----------|-------------|
| **Payment Amount** | Full amount paid by customer is transferred to your Hive account at settlement |
| **Monthly Invoice** | One invoice per merchant, per calendar month, in HBD |
| **Settlement** | Pay the invoice via a regular HivePay checkout URL |

---

## Tiered Rate Schedule

The fee rate applied to your monthly volume depends on the active **fee tier schedule**. Each tier has a USD-cent volume range and a percentage rate. The top tier is open-ended (`maxVolumeCents = null`).

The default schedule shipped with HivePay:

| Monthly Volume (USD) | Fee Rate |
|----------------------|----------|
| $0 – $999.99 | 1.5% |
| $1,000 – $9,999.99 | 1.0% |
| $10,000+ | 0.5% |

!!!info
The schedule is configurable per HivePay deployment. Always read the **current** schedule from your billing summary (`feeTiers`) rather than hard-coding rates — see [SDK Reference → Billing](/sdk/billing/).
!!!

The fee is calculated against your total processed volume for the month and issued as one invoice.

---

## Reading Your Billing Status

Use `GET /api/public/billing/me` (or `hivepay.billing.getMine()` in the SDKs) to read your current billing status. The response includes:

| Field | Description |
|-------|-------------|
| `currentMonth.totalVolumeCents` | Volume processed so far this month, in USD cents |
| `currentMonth.transactionCount` | Number of completed payments so far this month |
| `currentMonth.projectedInvoiceCents` | Projected month-end invoice at the prevailing tier |
| `outstandingInvoices[]` | Unpaid invoices, each with an `invoicePaymentUrl` for one-click checkout |
| `paidInvoices[]` | Historical paid invoices |
| `outstandingAmountCents` | Sum of unpaid invoice amounts |
| `totalPaidCents` | Sum of all paid invoice amounts to date |
| `feeTiers[]` | Active tier schedule with `minVolumeCents`, `maxVolumeCents`, `percentFee` |

+++ TypeScript
```typescript
import { HivePay } from '@hivepay/client';

const hivepay = new HivePay({ apiKey: process.env.HIVEPAY_API_KEY! });

const summary = await hivepay.billing.getMine();

console.log(`Volume this month: $${summary.currentMonth.totalVolumeCents / 100}`);
console.log(`Projected invoice: $${summary.currentMonth.projectedInvoiceCents / 100}`);

for (const invoice of summary.outstandingInvoices) {
  console.log(`Owed: $${invoice.invoiceAmountCents / 100} — pay at ${invoice.invoicePaymentUrl}`);
}
```
+++ PHP
```php
use HivePay\HivePay;

$hivepay = new HivePay(['apiKey' => getenv('HIVEPAY_API_KEY')]);

$summary = $hivepay->billing->getMine();

echo 'Volume this month: $' . ($summary['currentMonth']['totalVolumeCents'] / 100) . "\n";
echo 'Projected invoice: $' . ($summary['currentMonth']['projectedInvoiceCents'] / 100) . "\n";

foreach ($summary['outstandingInvoices'] as $invoice) {
    echo "Owed: \${$invoice['invoiceAmountCents']} — pay at {$invoice['invoicePaymentUrl']}\n";
}
```
+++ cURL
```bash
curl https://hivepay.me/api/public/billing/me \
  -H "Authorization: Bearer sk_live_xxx"
```
+++

---

## Invoice Lifecycle

```mermaid
stateDiagram-v2
    [*] --> open: Volume accrues
    open --> invoiced: Month-end roll-up
    invoiced --> paid: Merchant pays via invoicePaymentUrl
    invoiced --> overdue: Past due
    overdue --> paid: Late payment received
    paid --> [*]
```

| Status | Meaning |
|--------|---------|
| `open` | Period is the current month — still accruing volume |
| `invoiced` | Invoice generated and awaiting payment |
| `overdue` | Invoice has passed its due date (default 30 days) |
| `paid` | Invoice paid in full |

Outstanding invoices include an `invoicePaymentUrl` — a hosted HivePay checkout URL that pays the invoice in HBD. The same URL works for human merchants and for automated x402 settlements.

---

## Reading Tier Information Programmatically

Always use the `feeTiers` field on the billing summary to display rates — it reflects the schedule active for your account at request time.

+++ TypeScript
```typescript
const summary = await hivepay.billing.getMine();

for (const tier of summary.feeTiers) {
  const upper = tier.maxVolumeCents === null
    ? 'unlimited'
    : `$${tier.maxVolumeCents / 100}`;
  console.log(`$${tier.minVolumeCents / 100} – ${upper}: ${tier.percentFee}%`);
}
```
+++ PHP
```php
$summary = $hivepay->billing->getMine();

foreach ($summary['feeTiers'] as $tier) {
    $upper = $tier['maxVolumeCents'] === null
        ? 'unlimited'
        : '$' . ($tier['maxVolumeCents'] / 100);
    echo '$' . ($tier['minVolumeCents'] / 100) . " – {$upper}: {$tier['percentFee']}%\n";
}
```
+++

---

## Format Satoshis

Customer-facing payment amounts are denominated in satoshi strings. Use `formatSatoshis` to render them as decimals — there is no separate "fee" amount to compute, since the full payment is transferred to the merchant.

+++ TypeScript
```typescript
import { formatSatoshis } from '@hivepay/client';

console.log(formatSatoshis('10500')); // "10.500"
console.log(formatSatoshis('150'));   // "0.150"
console.log(formatSatoshis('1'));     // "0.001"
```
+++ PHP
```php
use HivePay\Fee;

echo Fee::formatSatoshis('10500'); // "10.500"
echo Fee::formatSatoshis('150');   // "0.150"
```
+++