API ReferenceBilling & Webhooks
Create a Stripe Checkout session for an active subscription plan.
const url = 'https://data.predictefy.com/v1/billing/subscribe';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"planId":"example","interval":"month"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://data.predictefy.com/v1/billing/subscribe \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "planId": "example", "interval": "month" }'Key-authed and WEIGHT 0 (starting a subscription never debits credits). The returned URL is Stripe-hosted; credit grants land later via the webhook's invoice.paid handler, from the plan's monthly_credit_grant. interval picks the billing interval: month (the default) bills monthly and grants one month of credits per paid invoice; year bills annually at twelve times the monthly price (no discount) and grants TWELVE months of credits up-front when the annual invoice is paid. A plan with no annual price answers 404 PLAN_NOT_FOUND for year. ONE LIVE subscription per account — 409 SUBSCRIPTION_EXISTS while an active, trialing, past_due, unpaid or paused subscription exists. An abandoned checkout does NOT lock the account out: while the previous Checkout session for the same plan and interval is still open, subscribing again RESUMES it and returns that same URL (never a second session); a different plan or interval replaces it, and an expired one is dropped for a fresh session. Only active rows with self_serve=true are purchasable; Enterprise is contract-only. 503 BILLING_UNAVAILABLE until the STRIPE_* env is configured.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
An ACTIVE, PRICED, self-serve plans id.
Billing interval. year charges the plan's annual price (12 x monthly) and grants twelve months of credits up-front on the paid annual invoice. Any other value is a 400.
Responses
Section titled “Responses”The hosted Stripe Checkout URL.
object
object
Examplegenerated
{ "success": true, "data": { "url": "example" }}Headers
Section titled “Headers”Net credits charged for this metered response after any error refund.
Post-charge account balance. Present only when the existing debit/refund operation made it available; the service never adds a database read solely for this header.
VALIDATION_ERROR — planId missing/invalid, or interval not 'month' / 'year'
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}Headers
Section titled “Headers”Net credits charged for this metered response after any error refund.
Post-charge account balance. Present only when the existing debit/refund operation made it available; the service never adds a database read solely for this header.
UNAUTHORIZED — platform lane (READS_ENABLE_AUTH)
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}SCOPE_MISSING — API key lacks the route's required scope (RBAC v1)
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}PLAN_NOT_FOUND — unknown, inactive, or unpriced plan, or no annual price for interval=year
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}Headers
Section titled “Headers”Net credits charged for this metered response after any error refund.
Post-charge account balance. Present only when the existing debit/refund operation made it available; the service never adds a database read solely for this header.
SUBSCRIPTION_EXISTS — account already has a live subscription, a completed checkout awaiting provisioning, or an in-flight checkout that could not be resumed
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}Headers
Section titled “Headers”Net credits charged for this metered response after any error refund.
Post-charge account balance. Present only when the existing debit/refund operation made it available; the service never adds a database read solely for this header.
RATE_LIMITED — per-key rps limit
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}Unexpected internal error after pricing. Retryable.
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}Headers
Section titled “Headers”Net credits charged for this metered response after any error refund.
Post-charge account balance. Present only when the existing debit/refund operation made it available; the service never adds a database read solely for this header.
BILLING_UNAVAILABLE (Stripe env absent) or PLATFORM_UNAVAILABLE (rate limiting down — a free side-effecting route fails CLOSED)
object
object
Always present on errors; quote this id when reporting a failed request.
Present only when a venue error is attributed to a specific exchange.
Example
{ "success": false, "error": { "code": "VALIDATION_ERROR" }}Headers
Section titled “Headers”Net credits charged for this metered response after any error refund.
Post-charge account balance. Present only when the existing debit/refund operation made it available; the service never adds a database read solely for this header.