Billing API

Manage subscriptions, create checkout sessions, and handle Stripe billing events.

Get Pricing Plans

GET /api/pricing

Returns available subscription plans with pricing details. Does not require authentication.

Response: 200 OK

[
  {
    "priceId": "price_abc123",
    "productName": "Formstamper Starter Monthly",
    "lookupKey": "monthly_starter",
    "amount": 2900,
    "currency": "cad",
    "interval": "month",
    "actionLimit": 10000
  }
]

---

Create Checkout Session

POST /api/checkout/create-checkout-session

Creates a Stripe Checkout session for subscribing to a plan.

Request Body:

{
  "priceId": "price_abc123",
  "howDidYouHearAboutUs": "internetsearch"
}

Response: 200 OK

{
  "url": "https://checkout.stripe.com/c/pay/..."
}

Redirect the user to the returned URL to complete payment.

---

Manage Subscription (Portal)

POST /api/stripe/create-portal-session

Creates a Stripe Customer Portal session where users can manage their subscription, update payment methods, and view invoices.

Response: 200 OK

{
  "url": "https://billing.stripe.com/p/session/..."
}

---

Stripe Webhooks

POST /api/stripe/webhook

Receives Stripe webhook events. This endpoint is called by Stripe, not by your application.

Handled Events:

• checkout.session.completed — New subscription created
• customer.subscription.updated — Plan changed or renewed
• customer.subscription.deleted — Subscription canceled
• invoice.paid — Payment successful
• invoice.payment_failed — Payment failed

note

This endpoint verifies the Stripe webhook signature to ensure events are genuine. Do not call it directly.

---

Subscription Object

When viewing user profiles or account details, subscriptions include:

{
  "publicId": "sub_01j5def456",
  "subscriptionId": "sub_1T56olC718gsxAw9UI3k1Gkv",
  "status": "trialing",
  "nickname": "Formstamper Starter Monthly",
  "lookupKey": "monthly_starter",
  "interval": "month",
  "amount": 2900,
  "currency": "cad",
  "actionLimit": 10000,
  "currentBillingPeriodStart": 1772120973,
  "currentBillingPeriodEnd": 1772725773
}

Subscription Statuses:

Status	Description
trialing	Free trial period
active	Paid and active
past_due	Payment failed, retrying
canceled	Subscription ended
unpaid	Payment retries exhausted