Subscription

Read the individual membership subscription on your personal account — 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). Subscribe flows through checkout; the API also exposes the same account-scoped maintenance actions used by the app: read a cancellation preview, cancel, update seat count, and add or remove family-member seats.

Building on the Prescribing API? Developer accounts have no subscription and these endpoints don't apply to them — prescribing-API reviews bill per outcome from prepaid credits, or by monthly invoice for enterprise accounts. See Pricing & Credits.

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

Cancellation preview

GET/api/v1/subscriptions/me/cancellation-preview

Calculates whether any current-period subscription amount is refundable before the user cancels. The refund amount is based on which patients have not had a prescription written in the current period, capped by what was actually paid this cycle.

Cancel subscription

POST/api/v1/subscriptions/me/cancel

Cancels the subscription. The request body is optional; pass refundIfEligible: true to request an immediate refund for any eligible no-prescription seats. Otherwise, or when nothing is refundable, the subscription cancels at period end.

Request

{
  "refundIfEligible": true
}

200 OK

{
  "refunded": true,
  "refundAmount": 9900,
  "effectiveDate": "2026-02-26T12:00:00Z",
  "subscription": { "...": "..." }
}

Update seat count

PATCH/api/v1/subscriptions/me

Parameter	Type	Required	Description
`seatCount`	integer	Required	Number of additional family-member seats. Must be >= 0.

Calls Stripe with immediate proration, then returns the updated subscription record.

Add or remove a patient with a seat

POST/api/v1/patients-with-seat

DELETE/api/v1/patients-with-seat/{patientId}

These convenience endpoints keep patient creation/removal and the matching non-self subscription seat in sync. The create body uses the same demographic fields as POST /api/v1/patients, including zipCode.