Stripe Billing & Vehicle Limits

​

Pricing model

# Price per vehicle per year in cents (€120.00 = 12000 cents)
PRICE_PER_VEHICLE_CENTS = 12000
PRICE_PER_VEHICLE_EUR = 120

# Payment history limits
DEFAULT_PAYMENT_HISTORY_LIMIT = 20
MAX_PAYMENT_HISTORY_LIMIT = 100

​

HTTP surface

​

Vehicle-limit enforcement

1. Enforced at POST /api/v1/drone (src/routes/drone_routes.py:99-108) — before any physical or SITL drone is provisioned. A denial returns HTTP 402 Payment Required with the reason, message, and subscription from the check.
2. Advisory at GET /api/v1/billing/can-add-vehicle (billing_routes.py:465) — so the Dashboard can grey out the “add vehicle” button before the user tries.

​

Subscription lifecycle methods

​

Webhook processing

​

Signature verification

if not settings.STRIPE_WEBHOOK_SECRET:
    if not settings.IS_LOCAL_ENVIRONMENT:
        logger.error("STRIPE_WEBHOOK_SECRET not configured in non-local environment, rejecting webhook")
        raise ValueError("Webhook signature verification not configured")
    logger.warning(
        "STRIPE_WEBHOOK_SECRET not configured, skipping signature verification (local environment only)"
    )
    event = stripe.Event.construct_from(...)
else:
    event = stripe.Webhook.construct_event(payload, sig_header, settings.STRIPE_WEBHOOK_SECRET)

​

Event dispatch table

​

Idempotent payment recording

existing_payment = Payment.query.filter(
    (Payment.stripe_invoice_id == invoice_id) | (Payment.stripe_payment_intent_id == payment_intent_id)
).first()
if existing_payment:
    logger.info(f"Payment already recorded for invoice {invoice_id}, skipping")
    return
try:
    payment = Payment(...)  # amount from invoice.amount_paid, currency default "eur"
    self._db.session.add(payment)
    self._db.session.commit()
except IntegrityError:
    self._db.session.rollback()
    logger.info(f"Payment already exists for invoice {invoice_id} (concurrent insert), skipping")

​

Data model

• subscription — one row per user (user_id is unique). Holds stripe_customer_id, stripe_subscription_id, status (SubscriptionStatus enum stored by value), vehicle_count (the Stripe line-item quantity, default 0), billing-period bounds, and canceled_at. is_active() → status in {ACTIVE, TRIALING}.
• payment — receipt history. amount is in cents (integer), currency defaults "eur", and stripe_invoice_id/stripe_payment_intent_id are both unique (the idempotency backbone). to_dict() adds an amount_formatted string like "€120.00".

​

Configuration

​

Gotchas for future editors

• Two sources of truth for price. PRICE_PER_VEHICLE_EUR (the display value from get_pricing_info()) is independent of the Stripe STRIPE_PRICE_ID (actual charge) — keep them in sync. PRICE_PER_VEHICLE_CENTS is dead code (referenced nowhere); it drives nothing.
• Quota math is vehicle_count-based, not “1 physical + 1 SITL”. Physical limit = vehicle_count; SITL limit = vehicle_count + 1. The free tier is exactly 1 SITL and applies to users with no active subscription.
• Enforcement lives at drone creation, returning HTTP 402. If you add a new provisioning path, it must also call can_user_add_vehicle — the check is not centralized in the service layer’s save() methods (see SITL Drone Lifecycle and Service Layer Overview).
• Webhook signature bypass is environment-gated. A non-local env with a missing STRIPE_WEBHOOK_SECRET rejects all webhooks; do not rely on the local bypass in staging/prod.
• invoice.paid is idempotent by design (dedup + IntegrityError catch). Preserve both unique constraints on payment.stripe_invoice_id and payment.stripe_payment_intent_id.
• Subscription.can_add_vehicle() on the model is dead-ish code relative to this flow — the route uses the service’s can_user_add_vehicle. Don’t confuse the two when refactoring.