Billing API

MimicBot billing is a thin wrapper around Stripe: the API starts Checkout sessions, opens the customer portal, and exposes the current subscription and usage. Plan changes, payment method updates, cancellations, and invoice history all go through the Stripe Customer Portal — the MimicBot API intentionally does not expose those mutations directly. Webhooks from Stripe keep the local subscriptions and usage rows in sync; you do not need to poll.

Endpoints

• Start a checkout
• Open the customer portal
• Get the current subscription

The subscription object

Field	Type	Description
plan	"free" | "starter" | "pro" | "agency"	Current plan id. Defaults to free when no subscription row exists.
status	"active" | "trialing" | "past_due" | "canceled" | "unpaid"	Stripe-mirrored subscription status.
cancelAtPeriodEnd	boolean	Whether the subscription is set to cancel at the end of the current period.
currentPeriodEnd	string | null	ISO 8601 of the current billing period end.
usage.messagesUsed	number	Chat messages consumed this period.
usage.messagesLimit	number	Plan's monthly message ceiling.
usage.botsUsed	number	Active bots (excluding soft-deleted).
usage.botsLimit	number	Plan's bot ceiling.
usage.pagesUsed	number	Indexed pages across all bots.
usage.pagesLimit	number	Plan's page ceiling.
usage.seatsUsed	number	Profiles in the agency.
usage.seatsLimit	number	Plan's seat ceiling.

Start a checkout

POST /api/billing/checkout

Creates a Stripe Checkout session for the requested plan. The response url is a hosted Stripe Checkout page — redirect the user there. On success, Stripe redirects back to /settings/billing?success=1 on the origin that made the request. The starter plan includes a 14-day trial automatically.

Request body

Field	Type	Required
plan	"starter" | "pro" | "agency"	yes

Request

curl -X POST https://api.mimicbot.app/api/billing/checkout \
  -H "Authorization: Bearer $MIMICBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "plan": "pro" }'

Response 200

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

Errors: 400 VALIDATION_ERROR, 401 UNAUTHENTICATED, 403 NO_AGENCY, 429 RATE_LIMITED (see Rate limits). See Errors.

Open the customer portal

POST /api/billing/portal

Creates a Stripe Customer Portal session. Use this to let customers change plans, update payment methods, cancel, or pull invoices without building any of that UI yourself. Requires the agency to already have a Stripe customer — if you haven't run a checkout yet, this returns 404 NOT_FOUND.

Request

curl -X POST https://api.mimicbot.app/api/billing/portal \
  -H "Authorization: Bearer $MIMICBOT_TOKEN"

Response 200

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

Errors: 401 UNAUTHENTICATED, 403 NO_AGENCY, 404 NOT_FOUND, 429 RATE_LIMITED (see Rate limits). See Errors.

Get the current subscription

GET /api/billing/subscription

Returns the agency's current plan, Stripe status, period end, and live usage counters. Usage counts are computed at request time from the database — there is no caching and no delay.

Request

curl https://api.mimicbot.app/api/billing/subscription \
  -H "Authorization: Bearer $MIMICBOT_TOKEN"

Response 200

{
  "plan": "pro",
  "status": "active",
  "cancelAtPeriodEnd": false,
  "currentPeriodEnd": "2026-05-01T00:00:00.000Z",
  "usage": {
    "messagesUsed": 1284,
    "messagesLimit": 10000,
    "botsUsed": 3,
    "botsLimit": 10,
    "pagesUsed": 812,
    "pagesLimit": 5000,
    "seatsUsed": 4,
    "seatsLimit": 10
  }
}

Errors: 401 UNAUTHENTICATED, 403 NO_AGENCY, 429 RATE_LIMITED (see Rate limits). See Errors.