Subscriptions

Manage your FiscalAPI subscription and merchant count. All endpoints require authentication.

Create a subscription

POST /v1/subscriptions

Creates a new subscription with Stripe billing. Each account can have one active subscription.

Request body

Field	Type	Required	Description
company_name	string	Yes	Company name (1-100 characters)
billing_email	string	Yes	Email for invoices and billing notifications
payment_method_id	string	Yes	Stripe payment method ID
merchant_count	integer	Yes	Number of merchants (minimum 1)
billing_interval	string	No	month or year (default: month)

Example

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"
  }'

Response 201 Created

{
  "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). See the Billing guide for pricing tier calculations.

Errors

Status	Error	Cause
400	company_name is required	Missing or empty company name
400	billing_email is required	Missing or invalid email
400	payment_method_id is required	Missing payment method
400	merchant_count must be at least 1	Zero or negative merchant count
400	billing_interval must be "month" or "year"	Invalid billing interval
409	subscription already exists	Account already has an active subscription

---

Update a subscription

PATCH /v1/subscriptions

Updates the merchant count for your subscription. Stripe automatically prorates charges for the remainder of the billing period.

Request body

Field	Type	Required	Description
merchant_count	integer	Yes	New merchant count (minimum 1)

Example

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

Response 200 OK

{
  "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": 30,
  "billing_interval": "month",
  "current_tier": "growth",
  "monthly_amount": 23000,
  "created_at": "2026-03-15T12:00:00Z"
}

Errors

Status	Error	Cause
400	merchant_count must be at least 1	Zero or negative merchant count
404	subscription not found	No active subscription for this account

---

Get subscription

GET /v1/subscriptions

Returns the current subscription for the authenticated account.

Example

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

Response 200 OK

Returns a Subscription object.

Errors

Status	Error
404	subscription not found

---

Subscription object

Field	Type	Description
id	string	Subscription identifier
account_id	uuid	Owning account identifier
stripe_customer_id	string	Stripe customer ID
stripe_subscription_id	string	Stripe subscription ID
status	string	Subscription status (active, suspended)
merchant_count	integer	Current merchant count
billing_interval	string	month or year
current_tier	string	Rate limit tier (starter, growth, scale, enterprise)
monthly_amount	integer	Monthly cost in cents
created_at	datetime	Creation timestamp