Billing API

Billing operations use GraphQL on the same endpoint as the rest of the API (POST / on the API origin). Authenticated mutations require a Clerk Bearer token.

Provider mode

query {
  billingProvider
}

Returns stub (default in development) or stripe. Clients use this to choose checkout UX.

Signup checkout

Create session

mutation CreateSignupCheckoutSession($input: CreateSignupCheckoutSessionInput!) {
  createSignupCheckoutSession(input: $input) {
    url
    sessionId
    checkoutSessionId
    provider
    alreadyComplete
  }
}

Input: planId (UUID), billingCadence (month | year).

Behavior:

• stub: alreadyComplete is true; redirect url points at the configured success URL with checkout_session_id.
• stripe: alreadyComplete is false; redirect url is the Stripe Checkout Session URL. The plan must have the matching stripePriceMonthlyId or stripePriceYearlyId configured.

Finalize after payment

mutation FinalizeSignupCheckout($input: FinalizeSignupCheckoutInput!) {
  finalizeSignupCheckout(input: $input) {
    id
    name
    planId
    planKey
    planName
  }
}

Input: checkoutSessionId from createSignupCheckoutSession (returned in the success URL query param checkout_session_id).

Idempotent: calling again returns the same workspace if already provisioned.

Legacy stub signup

completeWorkspaceSignup with stubCheckoutAck: true remains supported for older integrations.

Subscription query

query MySubscription($teamId: String!) {
  mySubscription(teamId: $teamId) {
    id
    status
    cadence
    currentPeriodStart
    currentPeriodEnd
    cancelAtPeriodEnd
  }
}

Requires team membership. Returns null when no subscription row exists.

Webhooks

Stripe sends events to POST /webhooks/stripe (not GraphQL). Only enabled when BILLING_PROVIDER=stripe. See internal docs for setup.

SDK

const provider = await client.billing.provider();
const session = await client.billing.createSignupCheckoutSession({
  planId,
  billingCadence: 'month',
});
const team = await client.billing.finalizeSignupCheckout({ checkoutSessionId });

Package: @mindsize/simple-feature-requests-sdk.