Subscription

Read your subscription state, payment method, and recent invoices. Useful for surfacing “am I a subscriber?” in an agent UI before attempting a one-call submission, and for showing billing history.

All endpoints require authentication (Clerk JWT or personal API key). Subscription writes (subscribe, change seat count, cancel) flow through the web checkout and customer portal — deliberately not exposed as direct programmatic endpoints.

Current subscription

GET/api/v1/subscriptions/me

Returns the user’s subscription record, mirrored from Stripe via webhook. Use status === "active" as the gate for one-call submission via /agent/query.

200 OK

{
  "id": "sub-uuid",
  "userId": "user-uuid",
  "stripeSubscriptionId": "sub_1A2B3C...",
  "plan": "base",
  "status": "active",
  "amount": 9900,
  "currency": "usd",
  "seatCount": 2,
  "currentPeriodStart": "2026-02-10T00:00:00Z",
  "currentPeriodEnd": "2026-03-10T00:00:00Z",
  "cancelAtPeriodEnd": false
}

Returns 404 if the user has never subscribed.

Default payment method

GET/api/v1/subscriptions/me/payment-method

Returns a minimal card summary — brand and last four digits. PAN, expiry, and CVC stay with Stripe; we never see them.

200 OK

{
  "brand": "visa",
  "last4": "4242"
}

Recent invoices

GET/api/v1/subscriptions/me/invoices

Returns the most recent Stripe invoices for the customer’s subscription. Each entry includes a hosted invoice URL the user can open to view or print the receipt.

200 OK

[
  {
    "id": "in_1A2B3C...",
    "number": "INV-001",
    "amount": 9900,
    "currency": "usd",
    "status": "paid",
    "hostedInvoiceUrl": "https://invoice.stripe.com/i/...",
    "invoicePdf": "https://pay.stripe.com/invoice/...",
    "createdAt": "2026-02-10T00:00:00Z"
  }
]