Overview

EdgeFlow SaaS uses Stripe for billing and subscription management. Organizations subscribe to one of four plans that determine device limits, API quotas, and available features. Usage is tracked in real-time and quotas are enforced automatically.

Subscription Lifecycle

┌──────────┐   subscribe   ┌──────────┐   payment ok   ┌──────────┐
│  (none)  │──────────────>│ Trialing │───────────────>│  Active  │
└──────────┘               └──────────┘                └────┬─────┘
                                                            │
                               ┌────────────────────────────┤
                               │                            │
                          payment fail                  cancel
                               │                            │
                               ▼                            ▼
                          ┌──────────┐               ┌──────────┐
                          │ Past Due │               │ Canceled │
                          └──────────┘               └──────────┘

Subscription States

State	Description
Trialing	Free trial period (up to 14 days)
Active	Payment successful, full access
Past Due	Payment failed, grace period
Canceled	Subscription ended
Unpaid	Invoice remains unpaid

Billing Cycles

Subscriptions support monthly and yearly billing with discounted annual pricing:

Monthly — Billed every 30 days
Yearly — Billed annually with discount

Usage Tracking

The platform tracks resource usage in real-time across multiple dimensions. Usage is aggregated hourly and daily for reporting.

Resource Type	Unit	Description
`device`	Count	Active provisioned devices
`api_call`	Count	REST API requests per day
`mqtt_message`	Count	MQTT messages processed
`data_transfer`	Bytes	Data transferred via tunnel
`deployment`	Count	Flow deployments per month
`flow_execution`	Count	Flow execution runs

Quota Enforcement

When a quota is exceeded, the platform returns 429 Quota Exceeded and blocks further operations of that type until the quota resets or the plan is upgraded. Quotas reset at the start of each billing period.

# Check current quotas
GET /api/v1/billing/quotas
Authorization: Bearer <token>

{
  "quotas": [
    {
      "resource_type": "device",
      "current_usage": 4,
      "max_limit": 5,
      "remaining": 1,
      "usage_percent": 80.0,
      "period_start": "2026-02-01T00:00:00Z",
      "period_end": "2026-03-01T00:00:00Z"
    },
    {
      "resource_type": "api_call",
      "current_usage": 3241,
      "max_limit": 10000,
      "remaining": 6759,
      "usage_percent": 32.4
    }
  ]
}

Subscription Management

# Get current subscription
GET /api/v1/billing/subscription
Authorization: Bearer <token>

# Create subscription
POST /api/v1/billing/subscription
{
  "plan_slug": "starter",
  "billing_cycle": "monthly",
  "trial_days": 14
}

# Upgrade/downgrade plan
PUT /api/v1/billing/subscription
{
  "new_plan_slug": "pro"
}

# Cancel subscription
DELETE /api/v1/billing/subscription?immediately=false

# Resume canceled subscription (before period ends)
POST /api/v1/billing/subscription/resume

Payment Methods

# Add payment method (Stripe payment method ID)
POST /api/v1/billing/payment-methods
{
  "payment_method_id": "pm_1abc...",
  "set_default": true
}

# List payment methods
GET /api/v1/billing/payment-methods

{
  "payment_methods": [
    {
      "id": "pm_1abc...",
      "type": "card",
      "brand": "visa",
      "last4": "4242",
      "exp_month": 12,
      "exp_year": 2027,
      "is_default": true
    }
  ]
}

# Remove payment method
DELETE /api/v1/billing/payment-methods/:id

Invoices

All billing activity generates invoices with downloadable PDF receipts:

# List invoices
GET /api/v1/billing/invoices?limit=10

{
  "invoices": [
    {
      "id": "inv_xyz789",
      "invoice_number": "INV-1708516800-abc",
      "status": "paid",
      "subtotal": 4900,
      "tax": 0,
      "total": 4900,
      "amount_paid": 4900,
      "amount_due": 0,
      "currency": "usd",
      "due_date": "2026-03-01T00:00:00Z",
      "paid_at": "2026-02-21T12:00:00Z"
    }
  ]
}

# Download invoice PDF
GET /api/v1/billing/invoices/:id/download

Promo Codes

EdgeFlow supports promotional discount codes with the following properties:

Percentage discount — e.g., 20% off for 3 months
Fixed amount discount — e.g., $10 off
Redemption limits — Max number of times a code can be used
Plan restrictions — Codes can be limited to specific plans
Expiration dates — Time-limited promotions

Stripe Webhooks

The platform processes Stripe webhook events to keep subscription state synchronized:

Event	Action
`customer.subscription.created`	Activate new subscription
`customer.subscription.updated`	Sync plan changes
`customer.subscription.deleted`	Mark subscription canceled
`invoice.payment_succeeded`	Record payment, update invoice
`invoice.payment_failed`	Mark subscription past due

Usage Reports

# Get usage summary for date range
GET /api/v1/billing/usage?start=2026-02-01&end=2026-02-21
Authorization: Bearer <token>

{
  "usage": [
    {
      "resource_type": "api_call",
      "total_quantity": 45230,
      "record_count": 21,
      "period_start": "2026-02-01T00:00:00Z",
      "period_end": "2026-02-21T00:00:00Z"
    },
    {
      "resource_type": "mqtt_message",
      "total_quantity": 128450,
      "record_count": 21
    }
  ]
}