Moonborn — API · billing
Create a paid subscription (or initiate hosted checkout)
When `paymentMethodId` is supplied, the subscription is created server-side. When `useHostedCheckout=true`, returns a Stripe Checkout URL and defers persistence to the webhook.
POST/v1/billing/subscriptionscope · Bearer (API key or session JWT)
Request body
| Field | Type | Description |
|---|---|---|
| planTierreq | string · "free" | "pro" | "team" | "enterprise" | |
| intervalreq | string · "month" | "year" | |
| stripePriceId | string | |
| paymentMethodId | string | |
| useHostedCheckout | boolean |
Responses
201Subscription created (or checkout pending)
Body
| Field | Type | Description |
|---|---|---|
| subscriptionreq | object | |
| subscription.subscriptionIdreq | string | |
| subscription.orgIdreq | string | |
| subscription.planTierreq | string · "free" | "pro" | "team" | "enterprise" | |
| subscription.statusreq | string · "trialing" | "active" | "past_due" | "canceled" | "incomplete" | "unpaid" | |
| subscription.intervalreq | string · "month" | "year" | |
| subscription.currencyreq | string | |
| subscription.recurringAmountMinorreq | number | |
| subscription.trialEndsAtreq | string | |
| subscription.currentPeriodStartreq | string | |
| subscription.currentPeriodEndreq | string | |
| subscription.cancelAtPeriodEndreq | boolean | |
| subscription.createdAtreq | string | |
| subscription.updatedAtreq | string | |
| checkoutUrlreq | string |
401Unauthenticated
Body
| Field | Type | Description |
|---|---|---|
| errorreq | object | |
| error.codereq | string | |
| error.messagereq | string |
402Card declined / payment failed
Body
| Field | Type | Description |
|---|---|---|
| errorreq | object | |
| error.codereq | string | |
| error.messagereq | string |
409Org already has an active subscription
Body
| Field | Type | Description |
|---|---|---|
| errorreq | object | |
| error.codereq | string | |
| error.messagereq | string |
422Validation error (unknown plan/interval mismatch)
Body
| Field | Type | Description |
|---|---|---|
| errorreq | object | |
| error.codereq | string | |
| error.messagereq | string |
Examples
cURL
curl -X POST https://api.moonborn.co/v1/billing/subscription \
-H "Authorization: Bearer $MOONBORN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"planTier": "free",
"interval": "month"
}'TypeScript
import Moonborn from '@moonborn/sdk';
const client = new Moonborn({ apiKey: process.env.MOONBORN_API_KEY });
const result = await client.billing.createSubscription({
planTier: "free",
interval: "month",
});Python
import os
from moonborn import Moonborn
client = Moonborn(api_key=os.environ["MOONBORN_API_KEY"])
result = client.billing.create_subscription(
plan_tier="free",
interval="month",
)