Billing Guide

FiscalAPI uses Stripe for subscription management with per-merchant volume pricing. Your monthly cost scales with the number of merchants you onboard.

Pricing tiers

FiscalAPI uses graduated (cumulative) pricing -- each tier applies only to merchants within that range:

Tier	Merchants	Price per merchant
Starter	1 -- 10	€9/month
Growth	11 -- 50	€7/month
Scale	51 -- 250	€5/month
Enterprise	251+	€3/month

Example calculation

For 30 merchants:

Range	Count	Rate	Subtotal
1 -- 10	10	€9	€90
11 -- 30	20	€7	€140
Total	30		€230/month

Annual billing

Choose annual billing (billing_interval: "year") for a discounted rate. Annual pricing is configured in Stripe and applied automatically when you create or update your subscription.

Creating a subscription

curl -X POST https://api.fiscalapi.com/v1/subscriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fsk_test_abc123def456..." \
  -d '{
    "company_name": "Acme Corp",
    "billing_email": "billing@acme.com",
    "payment_method_id": "pm_1234567890",
    "merchant_count": 10,
    "billing_interval": "month"
  }'

This creates a Stripe customer, attaches your payment method, and starts a subscription with the specified merchant count.

Response

{
  "id": "sub_abc123",
  "account_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "stripe_customer_id": "cus_abc123",
  "stripe_subscription_id": "sub_stripe_abc123",
  "status": "active",
  "merchant_count": 10,
  "billing_interval": "month",
  "current_tier": "starter",
  "monthly_amount": 9000,
  "created_at": "2026-03-15T12:00:00Z"
}

The monthly_amount is in cents (€90.00 = 9000).

Updating merchant count

As you onboard more merchants, update your subscription to reflect the new count:

curl -X PATCH https://api.fiscalapi.com/v1/subscriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fsk_test_abc123def456..." \
  -d '{
    "merchant_count": 30
  }'

Stripe automatically prorates the charge for the remainder of the billing period.

Checking your subscription

curl https://api.fiscalapi.com/v1/subscriptions \
  -H "Authorization: Bearer fsk_test_abc123def456..."

Rate limit tiers

Your subscription's merchant count determines your API rate limit tier:

Merchants	Rate limit tier	Requests/min
1 -- 10	Starter	1,000
11 -- 50	Growth	5,000
51 -- 250	Scale	5,000
251+	Enterprise	20,000

See the Rate Limiting guide for details on token bucket behavior and response headers.

Stripe webhooks

FiscalAPI processes Stripe webhook events to handle billing lifecycle changes:

Event	Action
invoice.payment_succeeded	Account restored if previously suspended
invoice.payment_failed	Account suspended, notification email sent
customer.subscription.deleted	Account suspended, notification email sent
customer.subscription.updated	Update logged

See the Stripe Webhooks API reference for endpoint details and signature verification.

Account suspension

If a payment fails or your subscription is cancelled, your account is suspended:

• API requests return errors
• Existing data is preserved
• Successful payment automatically restores access

A notification email is sent to your billing address when suspension begins.