URL: /guides/billing

---
title: Billing & Pricing
description: FormShield plans, credit weights per product, metered overage, and how to upgrade or manage your subscription from the dashboard.
---

FormShield bills in **credits**, not raw requests. One credit is the unit of metered usage; every product spends a fixed number of credits per call, and your plan includes a monthly pool of them. Heavier checks cost more credits, so a single shared balance covers every product on one bill.

## Plans

Every org starts on **Free**. Paid plans add a larger monthly credit pool and metered overage; Enterprise is unmetered and sales-led.

| Plan | Price | Monthly credits | Overage |
| --- | --- | --- | --- |
| **Free** | $0 | 10,000 | None — hard stop at the limit |
| **Pro** | $25/mo | 50,000 | $0.80 per 1,000 credits |
| **Business** | $99/mo | 300,000 | $0.60 per 1,000 credits |
| **Enterprise** | Custom | Unlimited | — |

<Note>
  The plan tier in the API and dashboard is one of `free`, `pro`, `business`, or `enterprise`. The marketing label for the `pro` tier is **Pro**.
</Note>

## Credits per product

Each product spends a fixed number of credits per call. The passive Content Protection beacon is always free, so you can instrument every pageview without touching your balance.

| Product | Endpoint | Credits per call |
| --- | --- | --- |
| **IP Intelligence** | `GET /v1/ip` | 1 (+1 only for `rdns` enrichment on a cache miss) |
| **Email Intelligence** | `POST /v1/email` | 3 |
| **Content Filter** | `POST /v1/check`, `POST /v1/content` | 2 |
| **Content Protection** — beacon | `handshake` / `collect` / `report` | **Free** |
| **Content Protection** — deep analysis | — | 4 |
| **Voight** | `POST /v1/challenge/verify` | 1 |
| **Auth Protection** | `POST /v1/sessions/resolve` | 2 |
| **Metering** *(coming soon)* | `POST /v1/meter` | 2 |
| **Auth Protection** — signup *(coming soon)* | — | 5 |
| **Commerce Protection** *(coming soon)* | `POST /v1/commerce/verify` | 30 |

The `region` and `company` IP enrichments are included at no extra credit; only `rdns` (reverse DNS) can add a credit, and only when the hostname isn't already cached. Every response reports the exact credits charged under `metadata` (and `metadata.enrichment` on `/v1/ip`), so cost is never a surprise.

## How metering and overage work

FormShield meters usage per org across the calendar billing period.

- **Free** hard-stops at 10,000 credits — calls past the limit return `429 QUOTA_EXCEEDED` until the period resets. The passive beacon path is never hard-stopped.
- **Pro** and **Business** soft-allow past their included credits and bill the overage to a [Stripe Billing Meter](https://stripe.com/billing) at the plan's per-1,000-credit rate. You're never blocked mid-month for going over.
- **Enterprise** is unmetered (quota-exempt).

Check your current usage any time:

```bash
curl https://api.formshield.dev/v1/orgs/{orgId}/usage \
  -H "Authorization: Bearer fs_live_…"
```

```json
{
  "plan": "pro",
  "monthly_quota": 50000,
  "used": 18240,
  "remaining": 31760,
  "period": "202606",
  "period_end": "2026-07-01T00:00:00.000Z",
  "overage": 0,
  "subscription_status": "active",
  "trial_end": null
}
```

When you're subscribed, `period_end` is your Stripe billing-period end (not the calendar month). `subscription_status` is one of `active`, `trialing`, `past_due`, `canceled`, or `incomplete`.

## The 14-day Pro trial

Upgrading to Pro starts a **14-day free trial that requires a card**. Stripe Checkout collects a payment method up front; you're not charged during the trial, and at day 14 the trial **auto-converts to paid Pro** unless you cancel first. There's no automatic drop back to Free — cancel from the billing portal before the trial ends if you don't want to continue.

While on trial, `GET /v1/orgs/{orgId}/usage` returns `subscription_status: "trialing"` and a `trial_end` ISO timestamp.

## Upgrade a plan (Checkout)

Start a subscription from your backend, then redirect the browser to the returned Stripe Checkout URL.

<Steps>
  <Step title="Create a checkout session">
    `POST /v1/orgs/{orgId}/billing/checkout` with the target plan. Requires the **manage billing** capability (org owner or billing role).

    ```bash
    curl -X POST https://api.formshield.dev/v1/orgs/{orgId}/billing/checkout \
      -H "Authorization: Bearer fs_live_…" \
      -H "Content-Type: application/json" \
      -d '{ "plan": "pro" }'
    ```

    The `plan` is `pro` or `business`. Optional `success_url` and `cancel_url` override where Stripe sends the user afterward.
  </Step>

  <Step title="Redirect to Checkout">
    The response is `{ "url": "https://checkout.stripe.com/…", "session_id": "cs_…" }`. Send the browser to `url`. Stripe handles the card and trial; on success the user returns to your `success_url`.
  </Step>

  <Step title="The webhook updates your quota">
    FormShield receives the Stripe lifecycle events at `POST /webhooks/stripe` and updates the org's plan, quota, and subscription status. The new credits are live within a few minutes.
  </Step>
</Steps>

## Manage billing (Portal)

To change a card, view invoices, switch plans, or cancel, open the **Stripe Billing Portal**.

```bash
curl -X POST https://api.formshield.dev/v1/orgs/{orgId}/billing/portal \
  -H "Authorization: Bearer fs_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "return_url": "https://app.formshield.dev/billing" }'
```

The response is `{ "url": "https://billing.stripe.com/…" }` — redirect the browser there. The portal requires the **manage billing** capability. Most teams do all of this from the dashboard's **Billing** page, which wraps both endpoints.

## Common questions

<ParamField path="What happens when I run out of credits?" type="question">
  On **Free**, calls past 10,000 credits return `429 QUOTA_EXCEEDED` until the month resets — except the passive beacon path, which is never hard-stopped. On **Pro** and **Business**, you keep working: usage past your included credits is metered as overage and billed at your plan's per-1,000-credit rate.
</ParamField>

<ParamField path="Is the beacon really free?" type="question">
  Yes. The passive Content Protection beacon (`handshake` / `collect` / `report`) costs zero credits, so you can record scored pageviews across your whole site without spending your balance. Deep analysis and the per-call APIs are what consume credits.
</ParamField>

<ParamField path="Do I need a card to try a paid plan?" type="question">
  Yes. The 14-day Pro trial is card-required — Stripe Checkout collects a payment method, you aren't charged during the trial, and it auto-converts to paid Pro at day 14 unless you cancel from the billing portal first.
</ParamField>

<ParamField path="How do I see what I've used?" type="question">
  Call `GET /v1/orgs/{orgId}/usage` for `plan`, `monthly_quota`, `used`, `remaining`, `period_end`, and any `overage`, or open the dashboard's Billing page for the same numbers with a usage chart.
</ParamField>

## Next steps

<CardGroup cols={2}>
  <Card title="API reference" icon="code" href="/api-reference/introduction">
    Authentication, the response envelope, and error codes including `QUOTA_EXCEEDED`.
  </Card>
  <Card title="IP intelligence" icon="globe" href="/products/ip-intelligence">
    The cheapest live product — one credit per IP lookup.
  </Card>
</CardGroup>